Aplication to add comments to my functions

[bim_bom]

I have a projet in C++ Builder.
I want to add aome lines of comment before each function of the project.
This should work like that:

I have function:
int r(int a,char b)
{
}

this program should generate a comment before this function like that:

/**
function name - r -
parameter a -
parameter b -
returns int -
*/

or something like that.

I found CommentMakerPro, but it can't do "batch conversions" - I nedd to
select each function/method and then click to generate comments. Is there
any program to do this automatically?

 

[David]

I have a projet in C++ Builder.
I want to add aome lines of comment before each function of the project.
This should work like that:

I have function:
int r(int a,char b)
{
}

this program should generate a comment before this function like that:

/**
function name - r -
parameter a -
parameter b -
returns int -
*/

or something like that.

I found CommentMakerPro, but it can't do "batch conversions" - I nedd to
select each function/method and then click to generate comments. Is there
any program to do this automatically?

Is there something wrong with "the human touch"? A simple copy and paste
operation will give you the prototype documentation. The important
details are the parameters, return values, and comments about the
methods. Humans are best at that.

In my opinion, most of these types of comments are useless to begin with
as they state the obvious. I'd rather see useful names and comments
about what is expected, returned, and a good description of the
operations involved.

Inline comments (those on bracket levels and where needed to explain
the code) are generally more useful than function headers.

I'd advise you to document and rework some or all of the code as you
visit each moduule or section of code. It takes a little longer at
first, but you can easily reformat and document hundreds or thousands
of lines per day. The added benefit is that you actually visited the
code and read what it is doing. You get to find problems and learn
what is in your code base.

The only true shortcut to making your code easy to use is to design
it that way. Tools may add a little fluff or reformat the code to
be easier to read, but unless you understand what it is that you
have, it is still just a mystery and you are doomed to wandering
around to find what you need or reinventing each solution as you
need it.

David

 

[Jim Langston]

I have a projet in C++ Builder.
I want to add aome lines of comment before each function of the project.
This should work like that:

I have function:
int r(int a,char b)
{
}

this program should generate a comment before this function like that:

/**
function name - r -
parameter a -
parameter b -
returns int -
*/

or something like that.

I found CommentMakerPro, but it can't do "batch conversions" - I nedd to
select each function/method and then click to generate comments. Is there
any program to do this automatically?

Why, for the sack of all that is right, would you want to do that?

int r(int a,char b)
is perfectly self documenting, as far as you want to extend it with
comments. You are giving absolutly no additional information with your
coments than the function call itself, and are taking up 6 lines of space.

This being the case, I would want to ask you why you wish to do this?
Perhaps Doxygen is what you're looking for?

That being said, it wouldn't be too difficult to write a parser to do this,
the main headache would be figuring out what is a function call and what
isn't.

 

[F.J.K.]

I have function:
int r(int a,char b)
{
}

this program should generate a comment before this function like that:

/**
function name - r -
parameter a -
parameter b -
returns int -
*/

Doxygen is the best semiautomatical documentation system I personally
know of. It runs as a standalone application and will produce a nicely
formatted HTML-documentation with relatively little effort.

Your above information would be contained in a block like (function
header is implicitly contained)
/**
@param a
@param b
@return
*/

Unless you intend to fill above "empty documentation", there's no use
in generating it at all, as doxygen can create the same html output
regardless.

If you want to fill it, modern development environments / editors
should have support for doxygen/JavaDoc/whateverDoc and produce the
above lines all by themselves. Kdevelop does, for example, with the
keyboard shortcut Ctrl Shift S.

If you are "batch-documenting" old software, just run a good
environment/editor like kdevelop, if need be on a VM. Otherwise writing
above lines manually doesn't really cost you anything, as they can be
written while thinking about the real content you want to fill in ;-)

Hope that helps, if somebody got a better way to document, I'd be
interested in knowing myself ...