Re: [PATCH] NTDLL atom.c documentation.

[Juan Lang]

Hi Max,
+ *  http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm

Please don't link to his site.  As I said in an unrelated message to
wine-patches last week, he used disassembly when performing his
analysis:
http://www.geoffchappell.com/viewer.htm?doc=notes/index.htm

I wouldn't want to endorse such an effort implicitly by linking to
him:  future Wine developers could be misled.

Thanks,
--Juan

[PATCH] NTDLL atom.c documentation.

[Max TenEyck Woodbury]

On 03/06/2011 10:34 AM, Juan Lang wrote:
> Hi Max,
> -
> - http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
>
> Please don't link to his site.  As I said in an unrelated message to
> wine-patches last week, he used disassembly when performing his
> analysis:
> http://www.geoffchappell.com/viewer.htm?doc=notes/index.htm
>
> I wouldn't want to endorse such an effort implicitly by linking to
> him:  future Wine developers could be misled.
>
> Thanks,
> --Juan

The list of entry point names and the version history is all I am 
interested in and I believe that does not require disassembly, but if 
you can point me at another source for that information, I will be glad 
to use that instead.

Max

[PATCH] NTDLL atom.c documentation.

[Nikolay Sivov]

On 3/6/2011 22:34, Max TenEyck Woodbury wrote:
> On 03/06/2011 10:34 AM, Juan Lang wrote:
> > Hi Max,
> > -
> > -
> >
> > http://www.geoffchappell.com/studies/windows/win32/ntdll/history/names40.htm
> >
> > Please don't link to his site.  As I said in an unrelated message to
> > wine-patches last week, he used disassembly when performing his
> > analysis:
> > http://www.geoffchappell.com/viewer.htm?doc=notes/index.htm
> >
> > I wouldn't want to endorse such an effort implicitly by linking to
> > him:  future Wine developers could be misled.
> >
> > Thanks,
> > --Juan
>
> The list of entry point names and the version history is all I am 
> interested in and I believe that does not require disassembly, but if 
> you can point me at another source for that information, I will be 
> glad to use that instead.

What's a point to make such changes in a first place? I don't see how 
it's useful to have automatically extracted partially filled function 
names from sources (if it's a purpose of these documentation headers of 
course). You always have sources, everything that might be useful for 
development is in as code or comments for not-so-obvious parts.

What is really helpful for documenting behaviour that isn't documented 
officially is writing test cases to show bugs or to prevent regressions.
> Max

[PATCH] NTDLL atom.c documentation.

[Max TenEyck Woodbury]

On 03/06/2011 02:45 PM, Nikolay Sivov wrote:
> What's a point to make such changes in a first place? I don't see how
> it's useful to have automatically extracted partially filled function
> names from sources (if it's a purpose of these documentation headers of
> course). You always have sources, everything that might be useful for
> development is in as code or comments for not-so-obvious parts.
>
> What is really helpful for documenting behaviour that isn't documented
> officially is writing test cases to show bugs or to prevent regressions.

What are you saying? I can't quite figure out your point.

There were no summaries for these functions before, mostly for
technical reasons, and this particular set is _not_ documented by
Microsoft. Juan Lang's point was about the quality of the source I was
using to check on the absence of documentation. I'm not sure that the
limited use I was making of that source would have the impact
predicted, but I'm willing to use another source if there is one
available. Your comments don't address that issue.

There are already test cases that define what the functions do, so that
is not the issue here. What is not currently being tested is the
behavior of the Microsoft code when it is being abused. In particular,
I see where passing pointers that cause faults can create problems and
have noted those places. Someone needs to look at those notes and
decide if they represent things that need testing. I suspect that they
represent very low priority issues.

I am noting where tests do and do not exist for particular entry
points, so that can't be your point.

I've been reading other peoples code for _decades_. This particular set 
of code is fairly clear with only a few arcane points, mostly to do
with 'integral' atoms. The notes I've added bring out this issue
somewhat more strongly than the code does. That should provide a clue
to why some of the minor twists in the code are there.

Maybe I'll see your point in the morning...

Max