New Template ParameterNotes

[Andreas_G]

Hi,

it would be nice to have a Template called

"ParameterNotes" which can be given to the %list% macro.

The ParameterNotes template should know all infos of the parameter dialog.

Here is an example for C++ code generation:

If this ParameterNotes template is defined like this

Code: [Select]

$comment = "@param"
$comment += "[" +  %paramKind% + "] "
$comment += %paramName% + " " + %paramNotes%
WRAP_COMMENT($comment, "80", "", "/// ")

And Operation template is defined like

Code: [Select]

//////////////////////////////////////////////////////////////////
/// %opNotes%
///
%list=ParameterNotes @separator="" @indent=""%  
%OperationDeclaration%
$bodyLoc = %opTag:"bodyLocation"%
%if opTag:"inline" == "true" or $bodyLoc == "header" or $bodyLoc == "classDec"%
%PI="\n"%
%OperationBody%
%endTemplate%

The output will be

Code: [Select]

//////////////////////////////////////////////////////////////////
/// This is the operation description
///
/// @param[in] param1 This ist the Desc of Param1. The exact
/// meaning of this parameter is here not importatant
/// @param[out] error      Tis is the errorcode
void myOperation(int param1, int& error);

would really be nice to have this. And would cause that we renew our license.   OK, I'm sure that we renew our EA license anyway, because EA is the best UML tool i ever have seen.

bye
Andreas

[Barry_Pearce]

Bit fickle eh? Anyway...developers shoud be looking in the model for documentation not the source code

Mind you it would be nice.

[AdamHearn]

You can get close with what's there now...

C++ code gen options:
Comment Style: XML.NET
Method notes: In header - I assume

This will provide you with some basic info although the formatting will not be as you desire:

Code: [Select]


     ///
     /// <param name="arg1">This is arg 1 notes</param>
     /// <param name="arg2">This is arg 2 notes</param>
     virtual void MyMethod(byte arg1, unsigned char arg2) =0;
Here's the Javadoc comment style:

Code: [Select]


     /**
      * @param arg1    This is arg 1 notes
      * @param arg2    This is arg 2 notes
      *
      */
virtual void MyMethod(byte arg1, unsigned char arg2) =0;


[Barry_Pearce]

Yeah that stuff already appears from the current CGT as you say...but the problem is the nice semantic information about in/out/in-out (and possibly fixed) have been lost and are not making it into the code.

[Andreas_G]

Anyway...developers shoud be looking in the model for documentation not the source code

You're right. However I develop a framework, and the ducumentation for it is generated out of the sourcecode by doxygen. That's the reason why i need the comments in the sourcecode.


I know both sulutions (the JavaDoc and the XML-Style). At the moment I use the JavaDoc-sulution like already discused in

the problem is the nice semantic information about in/out/in-out (and possibly fixed) have been lost

And the in, out, in-out problem is not fixed at the moment as you see in http://www.sparxsystems.com.au/cgi-bin/yabb/YaBB.cgi?board=general;action=display;num=1088595585.

[Barry_Pearce]

Incidentally ive recently logged an issue regarding lack of decent return documentation for an operation...which is the last bit of missing info about the method.

[Andreas_G]

Don't forget the exceptions

[Barry_Pearce]

Wellthats an interesting one as the throw specification is actually done via a tag rather than any direct support....which leaves documentation in a real limbo...

[bcgiMJ]

I've actually gone so far as to change the code generation templates for C++ in a number of ways, but with respect to return values I altered them so that tags of "return const" and "return reference" set to "true" do the obvious things, and checking the "Const" box in the operation dialog makes the operation a const member function, which seems more "correct" to me given how the other check boxes in that section are treated.

It might be nice if the UI allowed for return values from operations to have an associated "Fixed" checkbox and to allow selection of "return by reference" or "return by value" with the latter being the default. Then the tags would not be necessary.

One shortcoming I noticed (and corrected) is that if you mark a parameter to an operation as "inout" or "out" the generated code is still passing by value, not by reference. I changed the code template to pass in a C++ reference if the parameter is not "in".

[Eve]

Hi guys,

Just so you know.  Build 737 has the capability to define your own custom templates that will make the ParameterNotes template possible.  The only thing is that it will be Parameter__Notes.

Look at http://www.sparxsystems.com.au/EAUserGuide/customtemplates.htm for more information.

Simon