I use doxygen to document real-time kernel written in C, and for each function I should specify at least the following:
whether the function may be called from task
whether the function may be called from ISR
whether the function could lead to context switch
I'd like to implement these properties of functions as a kind of badge: probably just an image, probably an image with text, or something like that.
So, I'd like to put actual doxygen markup of all possible badges (currently, just three ones) in one place, and then just "include" them in the documentation of each function. Unfortunately I can't find anything about this in doxygen docs. I see there are methods to include source file as an example: \include, or even par or it: \snippet, but how to include documentation snippet?
I can't believe this isn't possible.
I failed to find some straightforward way, so I ended up with hacky makefile environment variables approach:
Makefile:
define \n
endef
TN_CALL_FROM_TASK = \image html attr_call_task.png ${\n}\
\latexonly \
\includegraphics{../../images/attr_call_task.png} \
\endlatexonly \
TN_CALL_FROM_ISR = \image html attr_call_int.png ${\n} \
\latexonly \
\includegraphics{../../images/attr_call_int.png} \
\endlatexonly \
export TN_CALL_FROM_TASK
export TN_CALL_FROM_ISR
all:
doxygen tn_doxyfile
And then, in the code:
/**
* Some docs for my function
*
* $(TN_CALL_FROM_TASK)
*/
void my_func(void) { ... }
It's not particularly elegant, but works.
Note one drawback of this approach: in doxygen 1.8.8 (latest at the moment), markdown syntax doesn't work when expanded from environment variables.
Related
I have a fair understanding of both how to document code and how to write "generic documentation" using #mainpage, #page, #subpage and related tags.
I would need to include requirements/specification documentation for the code.
My problem is to keep this kind of documentation (conceptually distinct from code documentation) close to code implementing functionality (i.e.: at least in the same file, sometimes even near specific classes/functions/methods) but still be able to collect it in an orderly fashion and present it in the #mainpage, outside file/class hierarchy.
What I would ideally need is to be able to place specific #page, #section, #subsection etc. randomly in the various source files and then be able to #include them in a specific order into #mainpage or some other #subpage.
Even better would be to be able to include the same snippet in both class/function full doc (not #brief, of course) and in the "front matter" linked in #mainpage.
Global effect I need to have is to have a "specification document" where I detail what the various parts of the code need to implement and then the "normal class/function/whatever" documentation doxygen id very good at providing.
The catch (i.e.: what I don't know how to do) is I would like to keep "specification" and implementation together in the source, but separate them in documentation, i.e.:
General Description: easy, this goes into #mainpage
Requirements: most likely at top of source file implementing them, how do I link/include in main page?
Specification: either right after Requirements at top of file or somewhere near class/function implementing it; also here I don't know how to link/include in "front matter" AKA: #mainpage.
Normal code documentation: here only thing I don't know is how include in class/function description the same "doc snippet" already used for (2) and (3).
Is this possible?
If so, what's the best practice?
Note: I could get the effect using a separate file for each "doc snippet" and then #includeing it in the right places, but that would defeat the whole purpose that's keep Requirements/Specification/code together while separating them in different sections in the resulting documentation.
Update: following #albert comment I tried the following:
in a standard Doxygen comment I added markers:
/**
* Initialization function.
*
* [AM_init]
* It needs to do a long series of tests to ensure AM can actually work.
*
* It should also allocate all dynamic memory needed to avoid runtime failures.
*
...
* It will be responsibility of system-level daemon to take appropriate action.
* [AM_init]
*
*
* #param ip_addr
* #param port
* #return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port) {
...
in the "front matter" definition I have (among other things):
/**
#page __init Initialization
#snippet{doc} CommandHandler.c AM_init
*/
The function documentation is rendered correctly (i.e.: the markers are removed)
OTOH the initialization page is "somewhat incomplete":
Initialization
It needs to do a long series of tests to ensure AM can actually work.
that's it.
Apparently the tag is found, but only the first line is actually included.
Further Update: Following #albert answer (accepted) I had success, but the following caveats:
Included snippet ([AM_init]) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.
Included snippet must not have leading * (very common in "standard comments".
Included comments should have HTML controls (e.g.: <br/> for line termination) because Markdown constructs ("double newline", in the above case) are notrecognized.
In retrospect I think "Note" in Doxygen \snippet['{'option'}'] <file-name> ( block_id ) documentation addresses, more or less all the above, but I find it very cryptic and I would never have understood the implications without my nose being rubbed into them.
The last one is very annoying because I use a lot Lists and Tables and while HTML syntax is much more powerful, it is also much more difficult to write and to read in sources.
Finding a way to lift this limitation would be "very nice".
With the following code and the current doxygen version (1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)) but also with the 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b) version, I get good result:
bb.h
/// \file
/**
#page __init Initialization
#snippet{doc} CommandHandler.c AM_init
*/
CommandHandler.c
/// \file
/**
* Initialization function.
*/
/* [AM_init]
It needs to do a long series of tests to ensure AM can actually work.<br>
It should also allocate all dynamic memory needed to avoid runtime failures.<br>
It will be responsibility of system-level daemon to take appropriate action.<br>
[AM_init]
*/
/**
* \snippet{doc} this AM_init
*
* #param ip_addr
* #param port
* #return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port){}
Doxyfile
EXTRACT_STATIC = YES
EXAMPLE_PATH = .
QUIET = YES
Note: OP rightfully mentioned in further update that there are some things to take care of:
Included snippet ([AM_init]) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.
Included snippet must not have leading * (very common in "standard comments".
Included comments should have HTML controls (e.g.: for line termination) because Markdown constructs ("double newline", in the above case) are not recognized.
When you run doxygen, you often get a lot of:
warning: some-thing-or-another is not documented.
For some items, you just want to fill in the documentation; but other are too trivial to document, or I just want listing without documentation.
Now, you could suppress these warnings with ///#cond and ///#endcond, but then the some-thing-or-another will be yanked out of the documentation, which is not what I wanted.
So, how can I make doxygen not warn me about certain items, while keeping the item in the documentaiton with no additional explanatory text?
A bit diving into the trick box.
Doxygen does have a command \noop but this is filtered out so it is not seen as documentation.
There are a number of non printing characters like and so defining something like:
/// \file
/** the documented fie
*/
void fie(void);
void fie1(void);
/** */
void fie2(void);
Will result in a warning for fie1 but not for fie and fie2.
The disadvantage is that doxygen thinks that fie2 is documented and thus creates a detailed section for it.
To overcome the "detailed section" problem one would like to have a command that says the function is documented but doesn't show anything and does not emit warnings about missing things, such a function is currently not present in doxygen.
Short version:
If I wanted to develop a completely new jsDoc template from scratch, what would I have to read to understand what jsDoc does, what interface my template must provide and what data I get to work with?
Long version:
I've been using jsDoc for a while now and have come across some tags that I would like to add and overview pages that I would like to have generated out of my documentation. Up to now I solved all my "user problems" with usejsdoc.org. I even managed to add a new jsdoc plugin that adds some tags. However, I can't find any developer documentation on how to create templates for jsdoc. I use ink-docstrap so I clicked my way through the template-folder (publish.js, /tmpl, etc.) and somehow got the idea of how everything works. But its very very time consuming.
What should I read to become a jsDoc template pro?
These instructions are the closest I could find:
To create or use your own template:
Create a folder with the same name as your template (for example, mycooltemplate).
Within the template folder, create a file named publish.js. This file must be a CommonJS module that exports a method named publish.
For example:
/** #module publish */
/**
* Generate documentation output.
*
* #param {TAFFY} data - A TaffyDB collection representing
* all the symbols documented in your code.
* #param {object} opts - An object with options information.
*/
exports.publish = function(data, opts) {
// do stuff here to generate your output files
};
To invoke JSDoc 3 with your own template, use the -t command line option, and specify the path to your template folder:
./jsdoc mycode.js -t /path/to/mycooltemplate
Failing that, you can read the source code!
I am running into a similar difficulty with lack of documentation. There is a GitHub issue that has been open for 7 years on this: Provide docs that explain how templates work.
The only example I've found so far of a custom template that doesn't look like just a modified version of the default is Ramda's documentation. It looks like they use a completely custom publish.js script that uses handlebars.js instead of underscore.js templates, constructs a non-hierarchical nav, pulls info from #sig and #category tags, and uses links to github for 'view source' instead of rendering its own html pages for source code.
Some of their code will be difficult to understand unless you are familiar with Ramda and functional programming (they use Ramda itself in their version of publish.js) but dumping out the values of data and docs during execution should help provide insight into what is going on.
It is helpful as well that their template is a single file so you don't have to jump between a lot of partial template files to follow how the doc is constructed.
I've just published my own new jsdoc theme. What I did is I simply copied the default template: https://github.com/jsdoc3/jsdoc/tree/master/templates/default, and worked on that.
I also managed to add grunt with the following features:
* transcompile + minify js files
* parse sass styles and minify them
* refresh the docs when you change something
You can see how it works here: https://github.com/SoftwareBrothers/better-docs
you can customize one of existing templates (default, haruki or silent):
go into node_modules/jsdoc/template and grab on of them into your app directory outside node_modules.
feel free to rename the dir ex: jsdoc-template.
open jsdoc-template update/customize the content as you want. ex: open publish.js find Home and replace My Js App.
update jsdoc.json by adding:
"opts": {
"template": "jsdoc-template"
}
another option to use one of those templates too: jsdoc3 template list examples
Followup to my previous comment about Ramda's JSDoc template. I've since created a customized version of it and published it on GitHub at https://github.com/eluv-io/elv-ramdoc
This is tailored for my company's projects, but it may be helpful as another learning tool. It adds a 'Show private' checkbox, updates Bootstrap to v5.13, replaces Handlebars with Pug, adds JSDoc comments to the publish.js script itself, and supports setting an environment variable to dump data to console during doc generation.
What would be best way to conditionalize text (not code).
There are 3 levels of documentation that I want conditionalized and tagged as:
Developer – This would be documentation that I don’t want doxygen to output at all. Such as notes to developers.
Internal – Information visible only for internal versions of documentation.
NDA - Information for customers plus anything not tagged as Developer or Internal; a subset of the Internal docs and would filter out internal websites for example.
There are a number of doxygen commands and configuration options which will help you achieve this. These include \internal and \endinternal. From the doxygen manual:
\internal This command starts a documentation fragment that is meant for internal use only.
You can use INTERNAL_DOCS in the config file to show (YES) or hide (NO) the internal documentation.
To address the three versions of documentation you want:
Developer: Use standard C/C++ comments, /* ... */. These won't be touched by doxygen.
Internal: For documentation only for internal use, use doxygen comments, /** ... */, and wrap these parts of the documentation with the \internal and \endinternal commands. When distributing the documentation internally set the configuration file option INTERNAL_DOCS to YES when building the documentation.
NDA: For documentation visable to the customer simply use doxygen comments /** ... */ and set the configuration optionINTERNAL_DOCS to NO in the configuration file when building the documentation.
In eclipse, when I want to document a function (in java or javascript source) I can just type /**, then hit enter, and I get a comment like this
/**
*
* Fluctuates all variables to more compatibly foo all the bars
*
* #PARAM {int} foo
*/
function flucvar (foo) {
}
When hitting enter inside the comment, eclipse automatically adds extra * at the beginning of each line.
Now I'm just getting into my textmate groove, and finding myself missing this little bit of functionality. Is there an equivilent bundle or command or something that would allow me to produce similar comments in textmate?
You need to create two snippets (I have them in the Source bundle).
First create a snippet for inserting JavaDoc comments. The snippet contains the following:
/**
* $0
*/
I have the snippet Activation set to Tab Trigger, using /** as the activation string. Every time I write /** and press Tab, I get a JavaDoc comment block. You can also use a keyboard shortcut if you like.
The second snippet is for continuing existing JavaDoc comments. The snippet contents are:
* $0
Note that there is an empty line before the * $0 line. Set Activation to Key Equivalent and the trigger key to return key. Set the Scope Selector string to comment.documentation.
Now if your language bundle supports the comment.documentation scope (like all of the included bundles seem to do), you should have working shortcuts for JavaDoc comments.
I took a look at TextMate's Java bundle, and I didn't see anything about inserting JavaDoc comments. However, it shouldn't be that hard to add such a feature to your Java bundle. It would likely be a Snippet, which you can read about in Chapter 7 of the TextMate manual (accessed from Help -> TextMate Help).
thanks for that answer. I just found this post on the macromates site
http://blog.macromates.com/2006/customization-screencast/
this appears to have a video/mailing list post that explains precisely how to do this.