JavaDoc comment construct "///<" in C++

[kalas]

I dislike the /** .. */ JavaDoc construct for class attributes or enums, because this makes the code very unreadable.

An example

Code: [Select]


/**
* Bus ID
*/
U8 m_u8BusID;
/**
* Identifies the Bus type
*/
ELinkType m_eLinkType;
/**
* Pointer to Link Process Data Adapter
*/
TcnLPA *m_pcLPA;
/**
* Pointer to Link Message Data Adapter
*/
TcnLMA *m_pcLMA;


instead I would like to use ///< construct

Code: [Select]


U8 m_u8BusID;          ///< Bus ID
ELinkType m_eLinkType; ///< Identifies the Bus type
TcnLPA *m_pcLPA;       ///< Pointer to Link Process Data Adapter
TcnLMA *m_pcLMA;       ///< Pointer to Link Message Data Adapter


When I reverse engineer such code, I see "< Bus ID" instead of expected "Bus ID".

I would like to have an option to generate such JavaDoc comments for attributes, and enum values too.

[Eve]

Hi Kalas,

You can modify the code templates to generate your comments like this. Although that even line of comments would be hard.  To do this you'll need to change the Attribute and Attribute notes templates.

With the reverse engineering you can't really avoid the "< " at the start of your comments.

I'm curious though.  Is that syntax an official standard anywhere.  I couldn't find it.  The closest was a feature request for javadoc to allow "///" comments.  According to that site it was "in progress".

[kalas]

It was my mistake, I referenced JavaDoc but we use Doxygen tool instead. This tools adds '/**< comment */' and '///< comment' syntaxes for comments put after code, and I thought this syntax was JavaDoc standard.

I agree that even line of comments is with current EA version impossible, but if there would be some support for this in next releases, it would be nice :-)

The aim here is to make the code as visually best readable as possible ...

[SF_lt]

as I remember, doxygen comments are:
///comment.

No < signs....

[Eve]

Hi Guys,

We don't currently include support for doxygen style comments.  That's something that we'll probably add in the future.

Until then the best possibility for reverse engineering formatted doxygen comments would be to reverse engineering them as plain, unformated comments. Then write an addin with the capability of iterating through the model and processing any formatted doxygen comments it finds.

For forward engineering you can manually modify the templates to generate doxygen style comments as I specified in my previous post.

[fprog26]

Doxygen comments which are right handed have an extra "<" character like this:

int x; ///<  some comment X
int y; //!<  some comment Y
int z; /**< some comment Z */

or like this:

int x;


///<  some comment X

int y;

//!<  some comment Y

int z;

/**< some comment Z */


The other possibility is like this:

/// Some comment X
int x;

//! Some comment Y
int y;

/** Some comment Z */
int z;

/** Some comment W */  int w;

The reasons for the extra "<" is that Doxygen use GNU Flex and whitespace considerations are not retained; therefore, a marker must be used to distinguish between the comment applies for the code after on the right-hand-side (Default) and the comment applies for the code before on the left-hand-side //!<

In EA, whitespace are retained in the parser and this is automatically done, so no need for the extra "<" character.

The only thing that needs to be done is very simple, just add a patch to the parser, such that
//!< ///< and /**< */ removes the extra "<" character.

Also, this form is also valid:
/**************************< Some comment */
/////////////////////////////////////////////< Some Comment

[Eve]

Sorry, it's not as simple as removing the '<' and '!' characters.

Using the '<' actually provides more flexibility than using the absolute file position, flexibility that is currently beyond EA code engineering.

A comment 'belongs' to an an attribute according to EA, if it is a line or two before it or is entirely on the same line.  This means that EA would incorrectly assign the comments in the second example.

Then there is parsing the Doxygen tags to enter the information into the model.

[fprog26]

I agree that it is not "simple" to provide all the feature of Doxygen in one go; however, like I said a short-term patch can be made such that it "seems" to works in "most cases". Which would be better than the current statu quo.

If it is wrongly assigned then we can still hand edit it ourself, like we currently do.

I really would appreciate like others if all doxygen style extension were supported like @param, \param, @author, \author, @return, \return, @see, \sa, @deprecated, @warning, etc.

At least, the major ones, more can be added in a "future version".
I'm sure some folks might use all of them, but these are the ones I use the most.

http://www.stack.nl/~dimitri/doxygen/commands.html

[Paolo F Cantoni]

If EA is to move into structured commentary (which I think would be a good thing) then I'd prefer a more abstract solution which could support multiple syntaxes in both directions.

My AU$0.05

Paolo

[fprog26]

Well, I think that being able to support "C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors) and to some extent PHP, C#, and D" and even some Javascript, in both directions (before or after the code) in contextual mode or out of context is quite interesting no?  

http://www.stack.nl/~dimitri/doxygen/