can you customizing code generation doxygen style?

[kenneth.nielsen]

I round trip with Native C++. And use doxygen commenting style, it works almost as i want it to ;^)
basically my ea. comments are wrapped in
/**
bla bla
*/
void blabla();

and i want them to be:
/// bla bla
void blabla();

- can I modify the way they are generated? ( like i can modify the way code is generate/analyzed, to place brachet
on a new line and not after function definition ?

Thanks for any anwser  
kenneth

[thomaskilian]

You can adjust the code gen macros in Settings/Code generation
Likely the reverse engineering will have trouble to RE the comments.

[kenneth.nielsen]

basically it looks like I want to change: JAVADOC_COMMENT
is that posible?
(it should then work both ways, is my guess)

[thomaskilian]

You can not change the macro itself. You have to replace it by something written on your own. I think that you can do that more or less inline (without having looked into details).

[david.kadlcak]

You can not change the macro itself. You have to replace it by something written on your own. I think that you can do that more or less inline (without having looked into details).

Do you have any pointers as to how one would go about doing that?  I just started evaluating EA 6.5 Pro and need to find out how much effort it would take to create a new macro something along the lines of CPPSTYLE_COMMENT

Also then, what would need to be changed to ensure that the same style is parsed in correctly when synchronizing the source with the model?

Thanks,
Dave.

[Eve]

You have a few options to get what you want.  Firstly, you could just use the JAVADOC_COMMENT macro and manipulate it.

Code: [Select]

$comment = %JAVADOC_COMMENT($wrapLen)%
$comment = %REPLACE($comment, "\n * ", "//  ")%
$comment = %REPLACE($comment, "/**\n//  ", "//! ")%
%REPLACE($comment, "\n */", "")%
Alternatively you can implement most of the javadoc comment macro yourself in the templates.  You'll need to create a custom template for the notes of the parameters and list over that from the operations template.

You could also use an addin and call EXEC_ADD_IN to format the comment how you want.

[Eve]

Alternatively you can implement most of the javadoc comment macro yourself in the templates.  You'll need to create a custom template for the notes of the parameters and list over that from the operations template.

If you want to see what this looks like, I've just added something into the EA Wiki that does it. http://wiki.eausergroup.org/index.php?title=CPP_Doxygen_Templates

[david.kadlcak]

Thanks Simon, that helps a little bit.  However, how will the source import do when we synchronize the model with the code.  From what I've seen, it imports the notes including the '!'.  So basicly, the round tripping breaks here without adjusting the import/parsing mechanism.

Second question I have here that kind of lead to this whole thing.  Under Tools->Options->Source Coding Engineering->C++ there's a option "Comment Style" that can be set to either:
"Plain"
"JavaDoc"
"XML.NET"
My question here is, is it possible for me to define a new "Comment Style", which would implement both Code Generation as well as Code Import (Synchronization) using C++ style doxygen documentation?  Or is that something that only you guys (Sparx) can do?

Dave.

[Eve]

No, we don't offer support of reverse engineering Doxygen comments.  Reverse engineering will add the '!' to your comments.  I offered the solutions I did only for forward engineering.  The only things I can offer you for reverse engineering is use one of the other commenting styles supported by doxygen (/** */ or ///) or to set EA not to reverse engineer comments.  (Tools | Options | Source Code Enginering | Comments | Reverse)

This last option will mean you can update your model from your code, but not mess up all of your notes.  It is generally useful whenever your comments contain metadata that EA doesn't know how to parse.

The list of comment styles available is fixed, and corresponds to the styles that EA code supports for reverse engineering and generating.  You can't add to it at all.

[kenneth.nielsen]

good answer,
thanks.
it looks like a change request about reverce engineering comments should be made to make it use the macro customization that you describe / design on the wiki.

[david.kadlcak]

Simon,

We've discovered a little problem with the suggested DOXYGEN_COMMENT template.

when the @param doxygen command is output using the DOXYGEN_COMMENT template, it is not parsed by EA when the code is reverse engineered.  The @param statement now appears in the Notes field of the class method.

so basicly the source looks like this:

/// @brief  Brief description of function here
///
/// Detailed description here
/// with multiple lines.
///
/// @param  inputMode This is the description for inputMode parameter
///
/// @param  secondVar This is the description of another parameter

When reverse engineered, the @param lines are included in the Notes for that class operation.

So, when doing recurring code generation and code synchronization, you can imagine that the @param statements rack up and are redundantly written back to the source file during code generation.

Is there a solution to this?

Thanks,
Dave.

[Eve]

If you're reverse engineering this set your C++ comment style to Javadoc.  That will make EA parse the @param tags correctly.

[david.kadlcak]

Thanks Simon.  That worked.  However, there were 2 more issues.  When parameter is type void, the template output @param prm1 into the source.  I fixed that by including an if statement in the Parameter__Notes template (see my talk addition on your wiki).

The bigger problem I have when reverse-engineering is that if the parameter is bool, it does not get parsed, and is added to the Notes of the operation.  This happens with Javadoc as well.  Type Int parameters are parsed in correctly.

Any ideas?  (use int instead?)

Dave.

[PogPower]

David, I've noticed that you used @brief tags.  Can you confirm that it also appears in the Notes field of the class method when reversed-engineered?  This is just to make sure I understand the way the reverse engineering function works.

Since we are using JavaDoc comment style for reverse engineering, only @param are interpreted (this tag is also a Javadoc Tag).  Is there any solution to support other Doxygen tags like @brief, except by coding a Addin?
 

[david.kadlcak]

David, I've noticed that you used @brief tags.  Can you confirm that it also appears in the Notes field of the class method when reversed-engineered?  This is just to make sure I understand the way the reverse engineering function works.

Since we are using JavaDoc comment style for reverse engineering, only @param are interpreted (this tag is also a Javadoc Tag).  Is there any solution to support other Doxygen tags like @brief, except by coding a Addin?
  

Yes we use the @brief command specifically to specify the brief description of classes, files, methods, etc.  Since Javadoc has "autobrief", it is not necessary to add the @brief to your notes.

While we're using the C++ style (///) it is acceptable for us that the @brief commands are not interpreted by EA and stay in Notes.  If I'm correct, EA does not have separate fields for brief descriptions and detailed descriptions.  That is something our project requires.

We also use the @return command in our Notes that stays in Notes.

This kind of behavior is okay, as long as information is not recursively re-created like it was the case with @param.

Dave.