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