[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