Documentation Generator?

[Strobe Raver]

Is there a documentation generator of putting in documentation?

Java's Documentation (example): http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html#wheretags

/**
     * Returns the character at the specified index. An index
     * ranges from <code>0</code> to <code>length() - 1</code>.
     *
     * @param     index  the index of the desired character.
     * @return    the desired character.
     * @exception StringIndexOutOfRangeException
     *              if the index is not in the range <code>0</code>
     *              to <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }

Thank you!

EDIT: Would there be a MASM-Style for documentation?

[Slugsnack]

there's no 'style' as far as i'm aware. just put your comments ( preceded by ; ) anywhere which will draw attention where needed. for example, after a variable to explain what it is for is a good idea. or for functions i usually do a new line under the proc line

but i'm not aware there is any strict style

maybe something you wanna do is under the proc, write what preconditions the function has, etc. really is up to you

[dedndave]

at the beginning of a procedure, i like to describe it's use and sometimes even it's theory of operation
but, always, it is nice to list "Call With", "Returns", and "preserved or used registers"
even if not for documenting it for someone else, if i want to use that proc someplace else 2 years from now, i can make use of it
also, if i want to add a feature to a program i have written, it is easier to see what i was thinking when i wrote it

[Strobe Raver]

Code Select Expand

proc uses eax, edi, ...

Use the above for sure?

[dedndave]

that is not really "documentation" per se
that tells the assembler that the prologue/epilogue needs to preserve those registers

[Strobe Raver]

Would it be alright if I use Java's style for method documentation?  :red

Code Select Expand

   * @param     index  the index of the desired character.
     * @return    the desired character.

[drizz]

I'm only aware of these two perl scripts from this page http://rudy.mif.pg.gda.pl/~bogdro/inne/ (AsmDoc and asm4doxy)
If anyone else knows of a tool that supports masm syntax please reply; I'm also interested in the subject.

[BATSoftware]

I say, write your own. I did. First is produced .HLP files, now, .HHP/HHC/.HTM files. Very easy thing to do, should take 3-4 days. Hint: use comments for documentation (ie. parse the source code for ;<code>).

For instance my documentation is found in my source code as follows:

;T LIB_CREATE_FONT - create a font for specified DC
;C DWORD LIB_CREATE_FONT(
;C DWORD DEVDC,
;C PCHAR FNAME,
;C DWORD CHARSET,
;C DWORD STYLE,
;C DWORD WEIGHT);
;P DEVDC Device context where font will be used (VALUE)
;P FNAME Font name (ASCIZ)
;P CHARSET Character set of font (VALUE)
;P STYLE Bit flag indicating style (VALUE)
;P WEIGHT Font weight (VALUE)
;R EAX - 0 = Error (use GetLastError)
;R   <>0 = Font handle
;N STYLE bits:
;N   Bit 0 - Italic
;N   Bit 1 - Underline
;N   Bit 2 - Strikethrough
;V 20090412 BAT
;E

Which is picked up by my hlp creator program to produce this (the index and keyword search is omitted):

LIB_CREATE_FONT - create a font for specified DC

Call:

DWORD LIB_CREATE_FONT(
DWORD DEVDC,
PCHAR FNAME,
DWORD CHARSET,
DWORD STYLE,
DWORD WEIGHT);


Parameters:

DEVDC Device context where font will be used (VALUE)
FNAME Font name (ASCIZ)
CHARSET Character set of font (VALUE)
STYLE Bit flag indicating style (VALUE)
WEIGHT Font weight (VALUE)


Returns:

EAX - 0 = Error (use GetLastError)

<>0 = Font handle


Notes:

STYLE bits:

Bit 0 - Italic
Bit 1 - Underline
Bit 2 - Strikethrough


Version:

20090412 BAT

Just remember to think simple (KISS principle) and apply a little parsing. THe results of producing your own documentation system is that you get to learn all about HTM and .CHM files.

Btw, the program to parse the source code is only 16K - eat that Microcrap!