I've just started using doxygen to document some legacy C code and I'm very impressed about what in can do even with un-marked up code. I've gotten the basics, annotating routines: brief, description, param, return, see, etc. That all appears (beautifully) in the generated documentation for the function. My question is: Can I put doxygen markup inside the routine, interspersed in the actual code, so comments that explain the "upcoming" section of code, can also be included in the documentation. Providing a stepwise overview of what the function does without having to copy those comments to the top of the routine?
Related
The company I'm working for does not use Doxygen, and in their coding standard explicitly prohibits "parseable comment styles such as javadoc, etc".
However, I've still found it very useful to run Doxygen myself just so I can see the class structure, and get nice per-class documentation of all the methods the a class has, including inherited ones.
The company does document the classes in the header files, with simple comments above each method declaration. It would be very useful if I could configure Doxygen to treat these comments as the function descriptions, even though they don't start with any Doxygen markers.
So: is it possible to get Doxygen to treat comments on the line above declarations as if they are the description for that item even when the comment is not marked with Doxygen's "parse this comment" markers?
The next best thing is to click on the #include <foo.h> links at the top of the class file to jump to the file itself, which I have been using. That doesn't help for seeing all of a derived class's methods in one place, though.
When the comments above the methods have only "normal" comments i.e. with /* or // the best thing to do would be that you write a small filter (see e.g. INPUT_FILTER with sed or awk or ... ) in which you convert (all?) /* / // comments into /** / /// so the comment blocks are parsed by doxygen. The result is not as nice as with "full" doxygen comments.
It is just a workaround and can lead to unexpected results when the INPUT_FILTER does not exclude e.g. // inside strings from consideration.
I am looking to have some snippets listed conditionally in the VS Code IntelliSense for a particular language. I am considering creating an extension, intercepting the list of CompletionItems, and removing any snippets that do not satisfy my conditions based on languageId and settings/configuration I will contribute with the extension. I am looking for the simplest solution to accomplish this, but if I need a Language Server then so be it. If I can dynamically load a snippets file for a particular languageId then that would be even better. I just need a starting point from someone more familiar with the API. I haven't even found how to retrieve CompletionList to start the intercept -- I searched the API doc but found nothing but its object definition.
As of VSCode 1.14, you cannot have conditional user snippets but an extension can contribute snippets conditionally. Try looking into creating a CompletionItemProvider that returns completion items with their kind set to CompletionItemKind.Snippet.
The JsDocCompletionProvider in the VSCode codebase is one example of this pattern. It only returns jsdoc snippets when the area around the cursor matches a regular expression
I have an OO project in MATLAB and would like to automatically produce some documentation.
After some research I have found a convenient tool called mtoc++ which apparently produces a documentation using Doxygen (I have no experience with).
My only question is whether in order to use the tool I need to write comments in MATLAB using a specific format (language?) so that mtoc++/Doxygen could understand and document my comments?
If so, then what this format/ language is and where I can find its description?
After correctly installing and configuring mtoc++/Doxygen, the documentation is created automatically.
If you want to define personalized comments for specific custom parameters, you can follow the instructions on this page:
http://www.ians.uni-stuttgart.de/MoRePaS/software/mtocpp/docs/tools.html
Look under the heading Configuration options for the mtoc++ filter.
What you have to do is to edit the mtocpp.conf file, located in tools/config folder, and the format you'll be using is this:
add(params) = <parameter1_name> => """Your parameter1 description text in triple quotes""";
An example would be:
add(params) = myVariable => """This variable is defined by me""";
So you can define personalized comments for your Parameters, Fields, Extra Documentation and Global Settings.
I am sure there must be other workarounds to add comments and documentation.
I hope this helps. Happy coding.
Is there a way to add comment to Simulink in a way which will be later added to the generated code?
Rational, sometimes i look at the generated code and I would like to see my comments for better understanding.
Within the Model-Wide Utilities library there is a DocBlock. If you select the Text option, then the comments can be included in code generated by Simulink Coder.
I'm new to CoffeeScript and seems that I can't find any document generator for CoffeeScript using Javadoc syntax. The only one I could find is available as a patch to the CoffeeScript compiler.
So, what do you use to generate documentation from Javadoc comment on CoffeeScript or how do you document your function arguments and return values?
So, JavaDoc syntax has never really caught on with JavaScript developers. There are those who use something like it—notably Google—but it's kind of at odds with JS, which doesn't have static typing and allows any number of arguments to any function.
If you want to create beautiful documentation with CoffeeScript, the standard is Docco (its home page is an excellent example). If you want to create JavaDoc-style comments for every function... well, you'll have to create them by hand, and escape them with backticks.
Alternatively, you could work in CoffeeScript until your code is release-ready, then document the resulting JavaScript.
Docco is great for prozedural coding style. If you want to document an API, coffeedoc is for you.
People looking forward to using javadoc style documentation in coffeescript can checkout codo ( http://netzpirat.github.com/codo/ ) which provides support for a subset of javadoc and automatically infers class names, function names and parameters from source code.
I'm using YUIDoc. I can add comments using a syntax similar to Javadoc to my classes, methods and events. The documentation gets output as html/css files and you can even customize the page layout.
Check this documentation example: http://yui.github.com/yuidoc/api/
PS: It relies on Node.JS and you need to install the package yuidocjs
npm install yuidocjs -g