API tracking and documentation

[Steven Edwards]

Hello,
The ReactOS project is interested in making a change to WINE the function commented that would
make API tracking a little nicer. We have implemented a web page like the mono project has that
shows the implemented and unimplemented functions in the API. Will the WINE project accept patches
to the comments to support this type of tracking system? It would be nice because you guys could
implement the same thing on your website. If the answer is no it is REALLY going to be a PITA for
us to diff our sources to yours for every function.

Please take a momenet to look at the site and how it works.
http://reactos.wox.org/index.php?page=apistatus

Here is the documentation for how we do it.

Abstract

Explains what tags are and how to use them.
TABLE OF CONTENTS

* 1 Overview
* 2 MS API compatibility

1 Overview

We define tagging a function as the process of associating metadata with a function. 
We define a tag to be a piece of information that has a well-defined meaning. 
A tag has one attribute - a name. The name of a tag always begin with the at sign 
(@) and it can include only the letters a-z and digits 0-9 and the underscore (_). 
Tagnames are case-insensitive. In the future a tag could have one more attribute - 
a value, but this is currently not needed.

In ReactOS, tags are currently only used to track compatibility with Microsoft APIs, 
but it could be used for so much more. Tags are applied to functions by including 
them in a comment just before the function. Eg. if you have a function called MyFunction, 
then you can tag it with the tag @mytag like this:

/*
 * @mytag
 */
VOID
MyFunction()
{
}

2 Microsoft API compatibility

Two tags are defined to track compatibility with Microsoft APIs. @implemented and 
@unimplemented. Apply @implemented to functions which match and behaves like a Microsoft 
API. Use @unimplemented to functions which match, but does not behave like a Microsoft API. 
The regenstat tool (located in reactos/tools/rgenstat) will parse the source code for 
these tags and generate an xml file containing functions that have these tags. The xml
 file can be processed by the rapistatus.xsl xml stylesheet (located in
reactos/tools/rgenstat/web)
 to create an html file suitable for display using a browser.


__________________________________
Do you Yahoo!?
SBC Yahoo! DSL - Now only $29.95 per month!
http://sbc.yahoo.com