Kernel code doc generator

NTDEV
1

Hello,

I’ve been using DoxyGen in my usermode code for a while to document it, but now I also want to document my KM code (preferably with Doxygen as well). I hope some of you have experience with this as asking on the Doxygen support forum hasn’t gotten me anywhere.

I want to automatically document driver annotations like __drv_maxIRQL. In Doxygen you can specify how a macro should be expaneded (e.g. __drv_maxIRQL(x)=\max_IRQL x) and you can add aliases (e.g. max_IRQL=“\par Max IRQL:\n”). Now if your source code you write \max_IRQL PASSIVE_LEVEL in a function’s documentation block it will in clude the Max IRQL paragraph.

The problem starts with for example:
\! \brief Function descr
__drv_maxIRQL( PASSIVE_LEVEL )
VOID myFunction();

With the above macro’s/defines it doesn’t see the max_IRQL as part of the function’s documentation, it creates a new global variables section:

Variables
max_IRQL PASSIVE_LEVEL

And the myFunction documentation will look like:
Max IRQL:
PASSIVE_LEVEL VOID myFunction()
Function descr

I guess it has to do with when the macro’s are expanded…

(This works:
\! \brief Function descr
\! \max_IRQL PASSIVE_LEVEL
__drv_maxIRQL( PASSIVE_LEVEL )
VOID myFunction();

Generates:
VOID myFunction();
Function descr
Max IRQL:
PASSIVE_LEVEL
)

But well, that’s way too ugly and redundant

Any other suggestions besides DoxyGen are welcome as well

Thanks

2

Doxygen is a great tool, but sometimes it makes me feel like I’m losing my
mind, and I suspect that this is one of those situations. It sure looks
like it should be possible and no doubt is, but I’ve never been able to get
this working without resorting to writing a prepreprocessor that translated
annotations (and some other things) into the appropriate doxygen special
comments, then running that output through doxygen.

If you do get it working, I’d love to know how.

Good luck/thanks,

mm

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of
xxxxx@gmail.com
Sent: Thursday, November 18, 2010 3:25 AM
To: Windows System Software Devs Interest List
Subject: [ntdev] Kernel code doc generator

Hello,

I’ve been using DoxyGen in my usermode code for a while to document it, but
now I also want to document my KM code (preferably with Doxygen as well). I
hope some of you have experience with this as asking on the Doxygen support
forum hasn’t gotten me anywhere.

I want to automatically document driver annotations like __drv_maxIRQL. In
Doxygen you can specify how a macro should be expaneded (e.g.
__drv_maxIRQL(x)=\max_IRQL x) and you can add aliases (e.g. max_IRQL=“\par
Max IRQL:\n”). Now if your source code you write \max_IRQL PASSIVE_LEVEL in
a function’s documentation block it will in clude the Max IRQL paragraph.

The problem starts with for example:
\! \brief Function descr
__drv_maxIRQL( PASSIVE_LEVEL )
VOID myFunction();

With the above macro’s/defines it doesn’t see the max_IRQL as part of the
function’s documentation, it creates a new global variables section:

Variables
max_IRQL PASSIVE_LEVEL

And the myFunction documentation will look like:
Max IRQL:
PASSIVE_LEVEL VOID myFunction()
Function descr

I guess it has to do with when the macro’s are expanded…

(This works:
\! \brief Function descr
\! \max_IRQL PASSIVE_LEVEL
__drv_maxIRQL( PASSIVE_LEVEL )
VOID myFunction();

Generates:
VOID myFunction();
Function descr
Max IRQL:
PASSIVE_LEVEL
)

But well, that’s way too ugly and redundant

Any other suggestions besides DoxyGen are welcome as well

Thanks

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

3

I was hoping (read: praying) that I wouldn’t have to resort to that. Unfortunately there has been no reply to my thread in the Doxygen forums.

The annoying thing is that the current solution with the macro expansion is so close to what we want… I am looking at the source code now to see if I can understand why it sees the expanded macro as a global comment… unfortunately they did not use terms like ‘alias’ or ‘predefined’ in their source.

I will post if I find something interesting

4

Thanks.

I went down the source code route as well, though several years ago. In the
end, I just gave up.

Good luck,

mm

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of
xxxxx@gmail.com
Sent: Thursday, November 18, 2010 4:08 PM
To: Windows System Software Devs Interest List
Subject: RE:[ntdev] Kernel code doc generator

I was hoping (read: praying) that I wouldn’t have to resort to that.
Unfortunately there has been no reply to my thread in the Doxygen forums.

The annoying thing is that the current solution with the macro expansion is
so close to what we want… I am looking at the source code now to see if
I can understand why it sees the expanded macro as a global comment…
unfortunately they did not use terms like ‘alias’ or ‘predefined’ in their
source.

I will post if I find something interesting

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:
http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

5

I too gave up several years ago as keeping with changes to doxygen and
to prefast annotations just got intolerable. If anyone comes up with a
good solution please do post it here.

Mark Roddy

On Thu, Nov 18, 2010 at 4:12 PM, Martin O’Brien
wrote:
> Thanks.
>
> I went down the source code route as well, though several years ago. ?In the
> end, I just gave up.
>
>
> Good luck,
>
> mm
>
> -----Original Message-----
> From: xxxxx@lists.osr.com
> [mailto:xxxxx@lists.osr.com] On Behalf Of
> xxxxx@gmail.com
> Sent: Thursday, November 18, 2010 4:08 PM
> To: Windows System Software Devs Interest List
> Subject: RE:[ntdev] Kernel code doc generator
>
> [QUOTE]
> writing a prepreprocessor that translated
> annotations (and some other things) into the appropriate doxygen special
> comments
> [/QUOTE]
>
> I was hoping (read: praying) that I wouldn’t have to resort to that.
> Unfortunately there has been no reply to my thread in the Doxygen forums.
>
> The annoying thing is that the current solution with the macro expansion is
> so close to what we want… I am looking at the source code now to see if
> I can understand why it sees the expanded macro as a global comment…
> unfortunately they did not use terms like ‘alias’ or ‘predefined’ in their
> source.
>
> I will post if I find something interesting
>
> —
> NTDEV is sponsored by OSR
>
> For our schedule of WDF, WDM, debugging and other seminars visit:
> http://www.osr.com/seminars
>
> To unsubscribe, visit the List Server section of OSR Online at
> http://www.osronline.com/page.cfm?name=ListServer
>
>
> —
> NTDEV is sponsored by OSR
>
> For our schedule of WDF, WDM, debugging and other seminars visit:
> http://www.osr.com/seminars
>
> To unsubscribe, visit the List Server section of OSR Online at http://www.osronline.com/page.cfm?name=ListServer
>

6

For what it’s worth, I think I got this particular one working, or
thereabouts:

(Salient) Doxyfile:

ALIASES = max_IRQL=“\par Max IRQL:\n”

ENABLE_PREPROCESSING = YES

MACRO_EXPANSION = YES

EXPAND_ONLY_PREDEF = YES

PREDEFINED = “__drv_maxIRQL(x)=//! \max_IRQL x”

HEADER:

//! \brief Function descr

__drv_maxIRQL(PASSIVE_LEVEL)

VOID myFunction1();

HTML:

Functions

VOID

myFunction1 ()

Function descr.

Function Documentation

VOID myFunction1

(

)

Function descr.

Max IRQL:

PASSIVE_LEVEL

Your code (the one that worked):

\! \brief Function descr
\! \max_IRQL PASSIVE_LEVEL
__drv_maxIRQL( PASSIVE_LEVEL )
VOID myFunction();

I assume that your use of ‘\!’ v. ‘//!’ is a typo.

Your ALIAS:

max_IRQL=“\par Max IRQL:\n”).

Mine:

ALIASES = max_IRQL=“\par Max IRQL:\n”

Your PREDEFINED:

\max_IRQL PASSIVE_LEVEL

Mine:

PREDEFINED = “__drv_maxIRQL(x)=//! \max_IRQL x”

I added the Doxygen comment marker ‘//!’ as a prefix. Without it, I’m not
sure what Doxygen thinks that it is.

mm

-----Original Message-----
From: xxxxx@lists.osr.com
[mailto:xxxxx@lists.osr.com] On Behalf Of Mark Roddy
Sent: Thursday, November 18, 2010 4:23 PM
To: Windows System Software Devs Interest List
Subject: Re: [ntdev] Kernel code doc generator

I too gave up several years ago as keeping with changes to doxygen and

to prefast annotations just got intolerable. If anyone comes up with a

good solution please do post it here.

Mark Roddy

On Thu, Nov 18, 2010 at 4:12 PM, Martin O’Brien

wrote:

> Thanks.

>

> I went down the source code route as well, though several years ago. In
the

> end, I just gave up.

>

>

> Good luck,

>

> mm

>

> -----Original Message-----

> From: xxxxx@lists.osr.com

> [mailto:xxxxx@lists.osr.com] On Behalf Of

> xxxxx@gmail.com

> Sent: Thursday, November 18, 2010 4:08 PM

> To: Windows System Software Devs Interest List

> Subject: RE:[ntdev] Kernel code doc generator

>

> [QUOTE]

> writing a prepreprocessor that translated

> annotations (and some other things) into the appropriate doxygen special

> comments

> [/QUOTE]

>

> I was hoping (read: praying) that I wouldn’t have to resort to that.

> Unfortunately there has been no reply to my thread in the Doxygen forums.

>

> The annoying thing is that the current solution with the macro expansion
is

> so close to what we want… I am looking at the source code now to see
if

> I can understand why it sees the expanded macro as a global comment…

> unfortunately they did not use terms like ‘alias’ or ‘predefined’ in their

> source.

>

> I will post if I find something interesting

>

> —

> NTDEV is sponsored by OSR

>

> For our schedule of WDF, WDM, debugging and other seminars visit:

> http://www.osr.com/seminars

>

> To unsubscribe, visit the List Server section of OSR Online at

> http://www.osronline.com/page.cfm?name=ListServer

>

>

> —

> NTDEV is sponsored by OSR

>

> For our schedule of WDF, WDM, debugging and other seminars visit:

> http://www.osr.com/seminars

>

> To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

>

—

NTDEV is sponsored by OSR

For our schedule of WDF, WDM, debugging and other seminars visit:

http://www.osr.com/seminars

To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer

7

I forgot that the HTML formatting would get trashed by Lyris, so you’ll have to take my word for it that the formatting is correct (or at least what I think that you are looking for).

Roughly:

Functions

brief function description VOID myFunction1()

Function Documentation

brief function description VOID myFunction1()

Max IRQL:
PASSIVE_LEVEL

mm

8

Ok I feel like an idiot now, adding the comment to the PREDEFINED works perfectly.
Isn’t it fun to spend a lot of time on things that turn out to be so simple :wink:

Thanks a million mm

9

Thanks for sharing the driver annotations suggestions.

As another Doxygen fan, one thing I never figured out was how to stop it
throwing up a warning about VOID functions not returning anything. I played
about with ALIASES and PREDEFINED to try to make it interpret VOID as void,
but never had any success.

I’m sure this is a problem which has a simple solution. Anyone know what
that solution is?

wrote in message news:xxxxx@ntdev…

Ok I feel like an idiot now, adding the comment to the PREDEFINED works
perfectly.
Isn’t it fun to spend a lot of time on things that turn out to be so simple
:wink:

Thanks a million mm

10

Glad we figured it out.

Mm
On Nov 19, 2010 7:17 AM, wrote:
> Ok I feel like an idiot now, adding the comment to the PREDEFINED works
perfectly.
> Isn’t it fun to spend a lot of time on things that turn out to be so
simple :wink:
>
> Thanks a million mm
>
>
> —
> NTDEV is sponsored by OSR
>
> For our schedule of WDF, WDM, debugging and other seminars visit:
> http://www.osr.com/seminars
>
> To unsubscribe, visit the List Server section of OSR Online at
http://www.osronline.com/page.cfm?name=ListServer