Hi James,
On Saturday 12 November 2005 02:52, James Hawkins wrote:
The proposed method is superfluous and adds unnecessary words to the docs and source. You really don't get any extra information by labeling a function as sketchy or substantial. It's dangerous to label a function as reviewed, because it gives the impression that the function is absolutely complete and free of bugs.
As Dimi pointed out, 'reviewed' is kind of orthogonal to the other keywords. So it's indeed probably a bad idea to mix it into an 'implementation status' annotation. But I would guess that most hackers won't be fooled into a '100% bug free' blindness by a tag like 'reviewed'.
We have a system right now that works well. The three states are stub, semi-stub, and implemented, though implemented is usually denoted by the absence of stub or semi-stub.
In my opinion it's not a good idea to interpret the absence of stub or semi-stub as 'implemented': I guess very few of wine's APIs would be considered implemented, yet most of them don't have a 'stub' or 'semi-stub' annotation. This would lead to a level of false positives, which would render the result almost meaningless.
A stub means nothing happens at all in the function; semi-stub means that the function does something, usually just enough to appease some apps; implemented obviously means it's implemented. This is also the easiest method in that you would just need to change c2man to parse the FIXMEs at the beginning for the word 'stub' or 'semi-stub'. They are already in most functions, and it would be beneficial to add them to the rest.
The problem with this is that it's not obvious that the presence of '(semi-)stub' in a FIXME macro has an effect on c2man. So it's kind of a hidden side-effect. If we instead put it in a special section in the API-comments, people will recognize it and start to immitate it.
If we can agree on a implementation status tagging scheme, it would be cool if we would write a small tool, which would scan for 'stub' and 'semi-stub' FIXMEs and map those to a 'STUBBED' or respectively 'SKETCHY' implementation status flag. This would give us a head start with the number of API's tagged.
Bye,