Measuring Wine's API completeness

[Michael Jung]

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,
-- 
Michael Jung
mjung at iss.tu-darmstadt.de