Audit the buttons code

[Shachar Shemesh]

Dmitry Timoshkov wrote:

>"Dimitrie O. Paun" <dpaun at rogers.com> wrote:
>
>  
>
>>I've explained that already: the comment's purpose is to identify
>>the *documentation* that the code has been audited against. Which
>>is the commctl 6.0 documentation. This is where MS says the standard
>>controls reside in XP, what's the problem?
>>    
>>
>
>The problem is that the documentation is misleading (intentionally or not it
>doesn't matter), and following a wrong doc is not what we want to do in Wine.
>
>  
>
I'm sorry for butting in on this. I don't understand your problem 
either. Dimi didn't change the location of the code - it's still in 
user32. Our dependencies won't change as a result of his patch, and it 
therefor follows that no program will break as a result of this comment.

What he did do, however, is carefully read the docs to find out how 
nuances work. He then proceeded to audit our code to make sure that it 
conforms. When you do such an audit, you do it against the docs, 
wherever they may be.

In this case, Dimi used version 6.0 of the comctl32.dll documentation. 
It can hardly be his fault that that's where the docs for button 
controls are. I don't think any amount of patch sending or arguing on 
our part is going to persuade Microsoft to move the docs elsewhere. 
Personally, I also see value in documenting what version of the docs the 
audit was performed against, so that future mismatches can be tracked down.

Can you suggest a better way to write the comment?

             Shachar

P.S.
Such comments do suffer from another problem. They tend to fall out of 
date. For that reason alone I'm not sure this comment is a good idea. 
Otherwise, we get a future commit that changes something, but neglects 
to update the comment accordingly, and the comment turns useless or even 
dangerous. Maybe if we change that to contain the date or the CVS 
version number of the file that was audited....

-- 
Shachar Shemesh
Lingnu Open Source Consulting ltd.
http://www.lingnu.com/