New c-mode Doxygen function documentation using Javadoc style tags.

[dpitic]

New Javadoc style tag Doxygen function documentation block for C functions.

[AndreaCrotti]

This looks exactly like this one
https://github.com/AndreaCrotti/yasnippet-snippets/blob/master/snippets/cc-mode/function_description

apart from the fact that there is a \ instead of @.
The @ seems like the right thing to use, would you mind just fixing the existing snippet instead of adding a new one?
Or maybe you think there was a reason for using \ @dpitic ?
Thanks for you contribution!

[dpitic]

It is exactly the same as the one you referenced because I used that one as the template. The original version uses the Doxygen style "\xxx" commands. My snippet uses the Javadoc style "@xxx" command which is also valid Doxygen command:
https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmd_intro

Specifically, I was working on a C project, which is why it went into the c-mode snippets directory. I haven't tested it with C++ project. Is there a better location in the snippet tree for this so that it works for C/C++ projects?

Also, I'm happy to change the expansion key to something more suitable if you have any suggestions?

[AndreaCrotti]

There is c-lang-common if that's what you meant for example?

[dpitic]

I'll test your suggestion and update accordingly. Thanks.

[dpitic]

I moved the file to c-lang-common as suggested and tested with C source file to ensure it still works.

[AndreaCrotti]

I'm a bit confused now @dpitic
you say your command uses the Java convention of using @, but at the same time you moved it to c-lang-common, which would not beh used for java-mode.

And why would you want to use the Java convention if you were working on a C/C++ project anyway?
So both styles are also valid in C/C++ projects right?

[dpitic]

My snippet uses the Javadoc style comment "@" which is valid Doxygen. It can be used to document any programming language. It's just a matter of style preference. Doxygen parses it identically to "\" in order to generate documentation. IDEs made by Jetbrains, Netbeans, Eclipse, and text editors like Sublime Text use this Doxygen documentation block to show function and other symbol documentation in the editor.

So, considering the fact that this is general Doxygen function block documentation that can be used for any language, is there a more appropriate location in the snippet tree where it should go?

[dpitic]

@AndreaCrotti I've updated the c-lang-common Doxygen function description block format.

I want to add an assembly language snippet. Should I do that in another branch in this fork, or create a new fork and pull request for that?

[dpitic]

@AndreaCrotti if you're still unsure about the @ JavaDoc style Doxygen command format, the official Doxygen website states that either \ or @ can be used:
https://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmd_intro

It's good to have both styles to cater for people with different preferences.

[AndreaCrotti]

Yes ok the current snippets we have don't have a great key either so maybe I can clean them up later on.