Fix function/variable parsing to allow comments in different places

Comments for functions do not not function as expected. I can give examples on request, but here are the issues I came across testing codedoc with a small file with just a single function defined.

1. If the return type is not void, there is a comment before the function, and there isn't a comment after the return type, the comment before the function becomes documentation for the return type and not for the function itself.
2. A multi-line comment after the return type breaks the documentation for the function itself.
3. Documentation comments for arguments only work if the parameter contains a comma after the parameter name.
4. Man pages do not show return type and parameter documentation.

After looking at the documentation, I can see why item 3 is an issue - the comment is to go after a comma or the closing parenthesis. I still think it would be nice to allow for the comment to be after the last parameter but before the closing parenthesis to allow for coding styles that put the closing parenthesis on the next line:

void
foo(
  int bar, /* bar comment */
  int baz /* baz comment */
) {
}

While writing this comment, I also realized that the above code will actually be parsed incorrectly and the documentation will show the signature as:

void foo(int bar);

This issue still occurs after removing /* baz comment */ but keeping the parenthesis on the next line.

Also I don't want to open another issue for this, but it would be nice if there was a way to put a comment at the beginning of a file and have it be top-level documentation.

[michaelrsweet]

@trbednarzyk Opened issue #10 to track top-level documentation comments.

I will look into ways of extending the code parser to support comments before the closing paren for the function...

I see you changed the title of the issue, but the new title ignores item 1 from my list.
An example for item one would be:

/* Example comment */
int
foo(void) {
}

This will result in Example comment being the documentation for the Return and not for the function foo.

Another interesting thing to note is the following:

int /* Return comment */
foo(void) {
}

This will have the signature int / foo(void); (note the forward slash).

[michaelrsweet]

I have my concerns about allowing/supporting cases where an argument or return value is not documented - normally that means "don't document anything about me" to codedoc...

Documentation should serve to add knowledge that's not immediately obvious by looking at the code (or in this case, the function signature).

Take for instance the following:

struct IntVector {
  int* elems;
  size_t num_elems;
}

void append_elem(IntVector* vector, int new_value);

I would say that the function append_elem should have a comment stating what it does. However, it is clear what the purpose of its parameters are simply by looking at the signature. I (personally) would not document these parameters as whatever I would type would just be redundant (though I wouldn't fault anyone who did so anyway).

[a-kramer]

I just noticed that this doesn't work at all:

/* function documentation*/
int /*return value documentation*/
function_name
 (int a, /* parameter a comment */
  int b) /* parameter b comment */
{
 //TODO
}

The above snippet creates no documentation at all, because there is a line break between the function name and the opening parenthesis. The following works:

/* function documentation*/
int /*return value documentation*/
function_name(int a, /* parameter a comment */
              int b) /* parameter b comment */
{
 //TODO
}

Maybe this is not such a big problem, but emacs by default aligns the function arguments in relation to the opening parenthesis. So, if you don't want the huge space before int b, you have to break before the parenthesis. This will also make code alignment independent of the function name length.