Re: [ros-dev] Tracking implementation API status

[Aleksey Bragin]

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

[Steven Edwards]

On Nov 10, 2007 4:00 AM, Aleksey Bragin <aleksey(a)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 Edwards

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Marc Piulachs]

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(a)reactos.org [mailto:[e-mail]] 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(a)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 Edwards

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo
_______________________________________________
Ros-dev mailing list
Ros-dev(a)reactos.org
http://www.reactos.org/mailman/listinfo/ros-dev

[Steven Edwards]

On Nov 11, 2007 9:50 AM, Marc Piulachs <marc.piulachs(a)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

"There is one thing stronger than all the armies in the world, and
that is an idea whose time has come." - Victor Hugo

[Timo Kreuzer]

Steven Edwards schrieb:
>   On Nov 11, 2007 9:50 AM, Marc Piulachs
> <marc.piulachs(a)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