Fix function/variable parsing to allow comments in different places about codedoc HOT 8 OPEN

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.

from codedoc.

@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...

from codedoc.

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).

from codedoc.

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...

from 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).

from codedoc.

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.

from codedoc.

@a-kramer I should probably fix that while I'm at it, although not just to support an eccentricity of Emacs... 😜

from codedoc.

I'm probably the worst emacs user, because I hardly ever re-configure anything :D "_o_/"

from codedoc.