#20 Function prototype categorization

[Thomas Bryan]

Submitted by Jonathan Pryor on Tue, 3 Aug 1999
18:32:20 -0400 (EDT)

It's nice to know that PERCEPS has a new
maintainer. I've been watching the previous
website for months with no updates, which had to
give me time to pause... This can only be a good
thing.

I've been using PERCEPS-style documentation in my
code for several months, and find it great.
There's just one minor problem that currently
annoys me -- function prototypes (outside of a
class/struct) don't seem to be handled correctly.

This is true for both 3.4.1 and 3.5.0.

For example, if I try the following prototype:

//: This is a function prototype.
void proto_func ();

PERCEPS seems to interpret it to be a global
variable (?!). At least, it gets located under
the "global" block in my index.html.tmpl file.

This would only be mildly annoying, but it gets
"worse" (from my perspective); if the function
takes /any/ arguments, it doesn't seem to be
interpreted at all:

//: no PERCEPS documentation is generated for this
function.
void ignored_func (char ch);

The only way to get PERCEPS to generate
documentation for global functions seems to be to
provide those functions with a function body:

//: This provides ``function'' documentation...
void documented_function (char ch)
{
}

Unfortunately, I'd rather not do this. My
preferred style is to provide function prototypes
in a header, place the PERCEPS documentation in
the header (with the prototypes), and then
implement the functions separately (with a note
stating that they should reference the
documentation in the header). I think this is
generally a good idea -- the header file contains
all the documentation, so it's not necessary to
view the function source to find the documentation
-- but PERCEPS doesn't support this style at this
point.

Moving away from the "practical" feature request
list, here's another one -- partly in jest.

It would be nice if it were possible to provide
JavaDoc-style
documentation.

Currently, many of my functions are similar to this:

//: Short description
//  Longer description
//\!param: foo - paremeter help
//\!return: Return value description
int my\_func \(char foo\);

I find JavaDoc much more pleasing on the eye:

/\*\*
 \* Short description \(first sentence\).
 \* Long description.
 \*
 \* @param  foo - parameter help.
 \* @return return value description
 \*/
int my\_func \(char foo\);

I suppose I like this form because everything is
logically in the same comment. It's not possible
(at least, not the last time I checked) to group
everything into a C-style comment in PERCEPS
(though I would find this useful as well). For
example, this won't work:

/\*: short description
 \*  Longer description...
 \*
 \*\!param: foo - parameter help.
 \*\!return: return value description
 \*/
int my\_func \(char foo\);

Instead, if you want to use C-style comments
(which I seem to prefer, for reasons I'm not
entirely aware of), this must be done:

/\*: short description. \*/
/\*  longer description, possible spanning
 \*  many lines...
 \*/
/\*\!param: foo - parameter help \*/
/\*\!return: return value description \*/
int my\_func \(char foo\);

Anyway, just some food for thought.

Good luck maintaining PERCEPS.

Jonathan Pryor