Sparx Systems Forum
Enterprise Architect => Suggestions and Requests => Topic started by: Derek Hoyle on February 19, 2011, 02:57:44 am
-
Hello,
I'd like to suggest that generated/synchronised code include comments for the parameters as well as the operations. Up until now we've been developing embedded code and documenting the API using Doxygen, so all of our code is commented and very easy to parse. e.g.
/** Converts an integer to a null-terminated string in the given radix.
* Takes a signed integer and converts it to its string representation using
* the given radix.
* If there is insufficient room, then the number is truncated MSD first. The
* null will always be written, provided that there is at least one character
* space available.
*
* \param str Destination string
* \param start First character to start converting. This must be the first
* digit of the prefix or the number itself if there is no
* prefix.
* \param i Input number to convert
* \param radix Base of string formatted number
* \param pad Minimum string length (string is padded with padCh
* if shorter). 255 characters max.
* \param padCh Character to pad empty space with.
* \param stringLength This is the limit of the string. No characters are
* accessed at or beyond this index.
*
* \returns position in string reached by the function. Points to the
* terminator if an error did not occur.
*/
size_t SafeStr_ItoStr( char_t str[], size_t start, sint32 i,
uint8 radix, uint8 pad, char_t padCh, size_t stringLength )
[size=10]Disclaimer - newer/more sophisticated documentation notations are also available for those under 35 ;)!! [/size]
This would make reverse-engineering our code-base even easier. Also, our good old boys who are happier in the code editor can hack-in the documentation as they are coding, as they have always done. At least, they always should have done.
I haven't tried Java or C# yet, but I guess you've got that covered??