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.
Related
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.
Consider this module App::TimeTracker. If you click on the tracker link in the SYNOPSIS section you end up here whereas you should have ended up here. The Pod source code responsible for the behavior is given here, which shows that the following Pod formatting code was used:
L<tracker>
I can fix the problem by providing an absolute link instead:
L<tracker|https://metacpan.org/pod/release/DOMM/App-TimeTracker-3.000/bin/tracker>
but this fixes the link to version 3.000 which may change in the future.
So how should this be done in general?
Use the full path without the version number: https://metacpan.org/pod/distribution/App-TimeTracker/bin/tracker.
The problem is that tracker_bash_autocomplete is not being indexed correctly as documentation by MetaCPAN. The NAME section has a very specific format based on manpages which must be adhered to for MetaCPAN to know how to link to your documentation. Putting tracker bash autocomplete before the hyphen makes MetaCPAN index it as tracker.
=head1 NAME
tracker_bash_autocomplete - whatever
I am working on this project : https://sbl.inria.fr/doc, where the documentation is done with doxygen.
We were used to define the id of our sections with the symbol "-" to separate the words, for example :
\section sec-intro Introduction
However, it looks like the convention has changed since doxygen 1.8.15-git and only alpha-numerical characters are accepted, breaking almost all the pages in our documentation.
Unfortunately, we have a large number of pages, and before reviewing the whole documentation, I wanted to know if there is anything that I am missing, like a doxygen option to turn ON / OFF
[edit]
Here is a minimal example that does not work for me, with doxygen 1.8.15-git:
/**
\mainpage My Main Page
Abstract
\section home-intro Introduction
Intro
*/
//! Documented class test
class test{
};
I just create the configuration file and then run doxygen on the directory containing my .hpp file (so that there is no need to specify the path to my header) :
doxygen -g; doxygen
The main page on the output html contains "Abstract", but not the section, and there is a warning in the doxygen log :
test.hpp:6: warning: Invalid section id `home'; ignoring section
[edit 2]
It worked with doxygen 1.8.14. I cloned the project from the git repository, so I had the latest version. Using the tag version for the 1.8.14, it works fine. I changed the title.
I found the cause of the problem, it is a regression on:
Bug 740046 - Negative sign in -Foo::Bar ruins hyperlink in generated output
The github issue causing the problem is https://github.com/doxygen/doxygen/pull/5677 and the pull request https://github.com/doxygen/doxygen/pull/704.
The issue has been fixed in the proposed patch: https://github.com/doxygen/doxygen/pull/6388
Some of my doxygen documentation need to refer to pages in the
company's wiki. I would prefer if these references resulted in working
hypertext links in the generated documentation. I could of course
achieve this by writing:
/// Name of page
or alternatively using Markdown syntax:
/// [Name of wiki page](http://long-URL.com/wiki/index.php?Name-of-page)
Unfortunately I have to give the full URL at every link in both cases,
and when (as has already happened) the base URL of our company/wiki
changes, all the URLs needs updating.
I therefore wonder if Doxygen has some support to avoid having to
hardcode the entire URL at every link?
For comparison, wikis use "InterMap" or "InterWiki", to define
prefixes that allow a shorthand notation for quickly referring to pages
on another web site. Example:
See WikiPedia:InterWiki_Links for more details.
So if possible I would like to let the Doxygen documentation contain
something like:
// See CompanyWiki:Name_of_wiki_page for bla bla
Some references:
Automatic link generation - http://www.doxygen.nl/manual/autolink.html
InterWiki - https://www.mediawiki.org/wiki/Manual:Interwiki
PmWiki/InterMap - http://www.pmwiki.org/wiki/PmWiki/InterMap
You could define an alias in the config file:
ALIASES += WikiPedia{2}="\2"
and then use it in your comments like so
See \WikiPedia{InterWiki_Links,Interwiki Links} for more details.
See also http://www.doxygen.org/manual/custcmd.html for more info.
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.