Opened 14 years ago

Closed 14 years ago

#207 closed defect (fixed)

Doxygen documentation style

Reported by: Jari Häkkinen Owned by: Peter
Priority: major Milestone: yat 0.4
Component: documentation Version: trunk
Keywords: Cc:

Description

I though there was a consensus on using the doxygen documentation style like

/**
...
*/
function();

Also I would like to change our previous usage of doxygen tags like @brief, @return to the more easy accessible '\' on mu keyboard, i.e., \brief, \return. Also, the '\' usage is more latex like. And I like them.

Anyway, there seems to be differen opinion on how to write doxygen comments. Please, speak up and make you thoughts heard.

Change History (4)

comment:1 Changed 14 years ago by Peter

Is this really a blocker? And it gotta be resolved before the upcoming release?

Anyway, I have no problem using \return instead of @return. Regarding the

/**
...
*/
function();

As I remember it Markus found that Doxygen has problem parsing / styles dox with a newline in the middle of latex code. Solution was to use the style above. I took this more as a technical note of making doxygen work more than a style decision. Hence the mixture of different styles.

Now when you bring this up on the table and make me think of it, I think it would be better to use the style above all the time, because you never know when it is time to use Latex in you documentation. And suddenly changing from one style to another makes the svn commits unnecessarily large. In other words breaking the commandment Commit often and do it minimalistic.

comment:2 Changed 14 years ago by Jari Häkkinen

Priority: blockermajor

If it is a blocker? Naeh, I just wanted it to light up. I don't expect us to fix anything in the code but I think we should add the doxygen style somewhere in the wiki.

comment:3 Changed 14 years ago by Jari Häkkinen

Milestone: 0.3 (Public release)0.4

Write down our ideas on the wiki.

comment:4 Changed 14 years ago by Peter

Resolution: fixed
Status: newclosed
Note: See TracTickets for help on using tickets.