Roundtrip Engineering with C++ and Doxygen comment style

[markuss]

Hi all,

there are several discussions about this topic, but they are quite old, and rather than replying the forum suggested to post a new one.

My primary goal would be a full roundtrip engineering using the Doxygen commenting style. Especially I would like to use
@brief for class and operation descriptions and
@param for operation parameters
@return for explanations on the returned values of operations

See Appendix below for an example of our commenting style.

It seems that EA 14 still does not support that. With the configuration I am currently using (see below) it does the following:

• adds the full class comment to the element notes of the class (with all "/**" etc. characters enclosing the comment)
• adds the attributes with their documentation, the "//"-comments are handled as desired: The "//" is removed and the comment is transferred to the attribute notes
• Adds the operations but ignores all comments - it just adds a generic comment somehow resembling the class name
• parameter documentation is entirely ignored

My major problem here is that I need to document a value range for the parameters of each method. Handling values outside this range will be subject to testing, and for tracing the test cases to these requirements, I will inevitably need this documentation in EA. And for usability reasons, I also inevitably need this documentation in the Doxygen comments.

So my questions are:
 

• Is there any way to synchronize parameter documentation with C++ comments (Whether in Doxygen style or not) without having to synchronize it manually?
• Is there a way to get rid of the Doxygen annotations (like @brief) in the class documentation that removed them from the element notes but keeps them in the C++ header?
• Older posts on this topic mentioned configuration options for handling comments in synchronization which I am unable to find in EA 14. Are they still present, and if so, how can I find them?

Thank you very much for any hints.

Appendix
Our commenting scheme looks like this:

[/list]

Code: [Select]

/**
 * @brief This is a class comment
 */
class ClassName
{
public:
/**
* @brief Verifies the parameters against the valid value range and then performs the operation. It uses the configuration file to...
*
* @param  [in] param1Name Description of parameter and value range
* @param  [inout] param2Name Description of parameter and value range
         *
* @return 1 in case of successful operation
         * @return -2 in case of insufficient memory
         * @return -4 in case that the configuration file is invalid
*/
int doSomething (const std::string &param1Name, std::string &param2Name);

private:
        // name of the configuration file
        std::string m_configFileName;
}


[bknoth2]

There are some synchronization options under Start/Preferences/Source Code Engineering/C++

Those don't cover everything you ask about.

- Bruce

[markuss]

Thank you so much, bruce, that was incredibly helpful to move a big step forward. I was desperately trying to find such options in Code->Options and ended up in the code templates.

My plan is now to do a reverse engineering of the initial model and then do unidirectional forward engineering of the headers. That would not be perfect but good enough.

A few questions are remaining for me. I would like to customize the comment generation by modifying the code templates. But I am unable to find...

... the documentation of "what is what", e.g. when generating the code for a class in the model, which code templates are used for which aspects of the class
... the definitions of macros. E.g. in the "Class Notes" template, macros called JAVADOC_COMMENT, CSTYLE_COMMENT,... are called, but I cannot find the place where I can change them
...how to use the values of custom tags assigned to a class or operation in the code generation template

Any pointer in the right direction (documentation) would be much appreciated.