Hi, no, I was speaking about something different. Take a look - http://www.reactos.org/wiki/index.php/Coding_Style there I mean this:
/*++ * @name SomeAPI * @implemented NT4 * * Do nothing for 500ms. * * @param SomeParameter * Description of the parameter. Wrapped to more lines on ~70th * column. * * @param YetAnotherParameter * Bleh, bleh :) * * @return STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL * othwerwise. * * @remarks Must be called at IRQL == DISPATCH_LEVEL * *--*/ NTSTATUS STDCALL SomeAPI( ...
rgenstat-alike tool should be able to parse such header, not only the old-style simple /* @implemented */
WBR, Aleksey Bragin.
On Nov 10, 2007, at 1:06 AM, Marc Piulachs wrote:
Hi Aleksey,
I don’t know if I understood you completely, rgenstat works by parsing c/cpp source files not header files. What do you mean with “standard function header”?
If we are seriously going to use it I would like to make some slightly modifications to it to make it more powerful but would require help from someone with more experience than me writing parsers in C.
Regards,
/Marc
On Nov 10, 2007 4:00 AM, Aleksey Bragin aleksey@reactos.org wrote:
Hi, no, I was speaking about something different. Take a look - http://www.reactos.org/wiki/index.php/Coding_Style there I mean this:
The implemented/unimplemented tags are really worthless because what if the API takes 20 params and 18 of them are implemented and nothing known uses the other 2 params? Do you call it implemented or unimplemented? Its better to autogenerate the docs from the function comment headers. See here, I think this is a MUCH better system and it already works. No point in developing another.
http://source.winehq.org/WineAPI/
If the API does not show up in the documented API then it should be safe to assume its not implemented. If it is implemented and not documented then its a Janitorial project.
Steven,
How different is the methodology used in wine from the one we want to introduce in reactos?
From what I understand wine uses a tool (doesn't matter which one now) to
parse C source files, extract function information (description , parameters, ...) from a more or less custom formatted header before each function and outputs HTML reports from it.
When I proposed to seriously use rgenstat on our core APIs I was thinking about doing something similar in concept but with a different implementation. Rgenstat is the C equivalent to the c2man script that inset of directly output formatted HTML outputs an xml database that is used as an intermediate format to generate HTML or whatever other format we may require in the future. The better solution for me is extending rgenstat to parse an strict doxygen style header with may be a few custom aditions (attributes) like @implemented/@unimplemented , @fixme , @winversion .... that make sense for our project.
It has the advantage that the same information from these headers can be used by doxygen to produce rich HTML in addition and for our custom API traking reports with our own particular information so from my point of view rgenstat (with a few modifications and enchantments to the parser) is more than sufficient.
Regards, /Marc
PS: The parser should be also tolerant to wine-style headers, of course.
-----Original Message----- From: ros-dev-bounces@reactos.org [mailto:ros-dev-bounces@reactos.org] On Behalf Of Steven Edwards Sent: Saturday, November 10, 2007 8:16 PM To: ReactOS Development List Subject: Re: [ros-dev] Tracking implementation API status
On Nov 10, 2007 4:00 AM, Aleksey Bragin aleksey@reactos.org wrote:
Hi, no, I was speaking about something different. Take a look - http://www.reactos.org/wiki/index.php/Coding_Style there I mean this:
The implemented/unimplemented tags are really worthless because what if the API takes 20 params and 18 of them are implemented and nothing known uses the other 2 params? Do you call it implemented or unimplemented? Its better to autogenerate the docs from the function comment headers. See here, I think this is a MUCH better system and it already works. No point in developing another.
http://source.winehq.org/WineAPI/
If the API does not show up in the documented API then it should be safe to assume its not implemented. If it is implemented and not documented then its a Janitorial project.
On Nov 11, 2007 9:50 AM, Marc Piulachs marc.piulachs@codexchange.net wrote:
How different is the methodology used in wine from the one we want to introduce in reactos?
Nothing really except the Wine one works and is fully functionally. I recommended ReactOS adopt it and the Wine comment style a long time ago but it never was because the project sometimes suffers from Not Invented Here Syndrome. If the other tool has all the same features and you can tweak it to be able to read the WineAPI docu then I don't really care. I am just saying here is another tool that already works well and has for years and the whole concept of @implemented and @unimplemented was just a bad idea. You might not have a choice but to use it though if you stub every function, as Wine uses the stub keyword in the dll spec file to determine the percent of the API that is actually implemented.
Steven Edwards schrieb:
On Nov 11, 2007 9:50 AM, Marc Piulachs marc.piulachs@codexchange.net wrote:
How different is the methodology used in wine from the one we want to introduce in reactos?
Nothing really except the Wine one works and is fully functionally. I recommended ReactOS adopt it and the Wine comment style a long time ago but it never was because the project sometimes suffers from Not Invented Here Syndrome. If the other tool
I don't think it's a "not invented here" syndrom. There's a standard in function headers, we already have in ntoskrnl, well mostly. @name MmIterateFirstNode, @param Node, ... and the @implemented just fits in there pretty good. It's not our standard, other tools like doxygen and codeblocks also support those headers. Wine headers don't stick to that standard.
We also should distingush between an apistatus and documentation that seems to get interchanged here all the time. An apistatus is only a quick overview to see if something is implemented or not. It doesn't say anything about how the function works, if there are bugs, etc. That's for the documentation. I agree that a simple @implemented or not doesn't say much about if something really works, but gives a good clue if something might work. If you see unimplemented for 5 of 6 functions you need, you know you will have a lot of work ;-) And if you look into our stubs.c files you will see that we still have lots of unimplemented functions.
If you want more detailed documentation, if something works or not: I have created an api testing framework, which is able to output test results as html, where you can quickly see, if something works or not and if there are regressions. We would only need a huge bunch of tests...
Regards, Timo
-
Aleksey Bragin -
Marc Piulachs -
Steven Edwards -
Timo Kreuzer