documentation generation

ç i p h é r · Post by **ç i p h é r** » Sat Jul 08, 2006 1:14 pm

Thanks for the clarification. It's clearly very intentional then.

peterdin · Post by **peterdin** » Sat Aug 12, 2006 1:29 pm

I have changed the comments of all ISS files currently in the repository

results can be found here http://www.chalana.nl/alfa2/

If needed I can commit the changed files back to the repository so we have a start here.

let me know what is needed.

ç i p h é r · Post by **ç i p h é r** » Sat Aug 12, 2006 3:04 pm

Interesting. I looked at one of the files I committed using the comment standard you noted above (//!) but it seems as though it's now picking up all comments? Is this what you modified?

I'm not sure if the output needs tweaking or if it's how I've commented, but I'm seeing comments from within functions show up now and comments around prototypes that do not show up at all. Look at acr_resting_i for instance under RULES. Seems a bit off....

peterdin · Post by **peterdin** » Sat Aug 12, 2006 3:18 pm

can you give an example of a missing prototype documentation and one of the comments from within a function.

can't find them that quickly

ç i p h é r · Post by **ç i p h é r** » Sat Aug 12, 2006 3:56 pm

Source:

http://svn.sourceforge.net/viewvc/alfa- ... iew=markup

Document:

http://www.chalana.nl/alfa2/acr__resting__i_8nss.html

Look at any of the function prototypes and their comments. Only the first line appears to get used. Am I using the wrong comment prefix?

peterdin · Post by **peterdin** » Sat Aug 12, 2006 6:01 pm

if you look at a previous post there is a brief comment and an extended comment

I adjusted the comments such that the first line only shows up in the brief comments and the rest will show up in the extended comments (this can be read when you clik on the function name on the top, it'll jump to the function documentation showing more detail)

it is good to remember that the brief comment can hold only 1 line.

does this solve the issue?

ç i p h é r · Post by **ç i p h é r** » Sat Aug 12, 2006 6:02 pm

Sounds like it. Let me take another look.

peterdin · Post by **peterdin** » Mon Aug 14, 2006 6:29 pm

any news on this yet?

The sooner we get this into the archive the better it is.
As said, I have changed all the _i files and they're ready to be posted.

ç i p h é r · Post by **ç i p h é r** » Mon Aug 14, 2006 7:43 pm

Yeah, there is. While I now understand the brief/expanded views, there are still some quirks. Refer to the code and documentation for comparison as linked above:

1. indentation in the documentation is odd, it doesn't match the actual comments - see _playerHasBedroll()
2. expanded display is really off in some places - see _playerCanRest()
3. it looks like standard comments using the prefix // are being picked up in the expanded view (they shouldn't - only //! should, right?) - see _playerCanRest()

Other than that, it looks great! Good work peterdin.

peterdin · Post by **peterdin** » Tue Aug 15, 2006 6:55 am

I'll have a look at it and sort it out.

peterdin · Post by **peterdin** » Wed Aug 16, 2006 8:08 pm

ç i p h é r wrote:Yeah, there is. While I now understand the brief/expanded views, there are still some quirks. Refer to the code and documentation for comparison as linked above:

1. indentation in the documentation is odd, it doesn't match the actual comments - see _playerHasBedroll()
2. expanded display is really off in some places - see _playerCanRest()
3. it looks like standard comments using the prefix // are being picked up in the expanded view (they shouldn't - only //! should, right?) - see _playerCanRest()

Other than that, it looks great! Good work peterdin.

1: has todo with the use of "-" in the comments. use \param for parameter descriptio and \return for return description
2: see 1
3: that's because I did a global replace of // whit //!

I have uploaded some changes at the url provided earlier (only the resting file I've changed )
It looks better now, there's only 1 thing: new lines are not included. It glues everything together.
I have to sort out why, but I run out of time.

ç i p h é r · Post by **ç i p h é r** » Wed Aug 16, 2006 8:50 pm

Ok so just to be clear:

INCORRECT:
//! - Param1: first argument
//! - Returns:
//! - 1: success
//! - 0: fail

CORRECT:
//! \param Param1: first argument
//! \return Returns:
//! \return 1: success
//! \return 0: fail

Is this the right interpretation? Or does anything after \param or \return need to be on one line as well?

Things look better but yeah, still needs a few tweaks.

peterdin · Post by **peterdin** » Thu Aug 17, 2006 6:03 pm

CORRECT:
//! \param Param1 first argument
//! \return
//! 1: success
//! 0: fail

question: does the script compiler support this style:
/* \param Param1 first argument
\return
1: success
0: fail
*/
it looks like the doc generator has some problems with multiple lines in combination with the //! style comment.

peterdin · Post by **peterdin** » Sat Aug 19, 2006 3:06 pm

well Ihave figured it out (at last *sighs)
have a look at the resting doc on the previous posted link.
Doxgen will glue everything togehter in one paragraph. If a new line is needed, add a \n.

snippet of the code:
//! This function determines if a player is allowed to rest (heal and restore spells).

//! \param oPC: player attempting to rest
//! \return
//! 1 - can rest\n
//! 0 - is not tired\n
//! "-1" - cannot rest\n
//!
//! Triggers must be setup for the following conditions:\n
//! indoor rest zone (for inns/rooms only - does not require bedroll)\n
//! outdoor rest zone (for wilderness only - requires bedroll but rest anytime)\n
//! Spot/Search widget - detect rest zones (terrain suitable for resting w/o a bedroll)\n
int _playerCanRest(object oPC);

btw: followoing gives the same results, perhaps a matter of taste(or style guide). btw: do we have a rule which says which style to use?
/*! This function determines if a player is allowed to rest (heal and restore spells).

\param oPC: player attempting to rest
\return
1 - can rest\n
0 - is not tired\n
"-1" - cannot rest\n

Triggers must be setup for the following conditions:\n
indoor rest zone (for inns/rooms only - does not require bedroll)\n
outdoor rest zone (for wilderness only - requires bedroll but rest anytime)\n
Spot/Search widget - detect rest zones (terrain suitable for resting w/o a bedroll)\n
*/

ç i p h é r · Post by **ç i p h é r** » Sat Aug 19, 2006 7:36 pm

I see. Definitely more orderly now but it looks to me like the brief description (one liner) is gone. Do you notice that too?

About // vs /* */, no there's no hard style rule on that but I prefer // for most comments (it's easier) and reserve /* */ for when I need to comment out blocks of code that I don't want to delete. Also, I find that the // prefix on evey comment line makes files more readable, but again, it's mostly preference. If we need to standard to accommodate doxygen, then we can go with strictly one method.