What I would like is to write something like this:
/**
* Takes a foo and {#link grokelates} it.
*/
function doSomething(foo) {
}
And have "grokelates" be a link to more detail on what "grokelate" means, but because I'm going to have functions dealing with grokelation all over my code base, I'd like to write that definition once and link to it in multiple places.
Is this possible?
To be clear, grokelates is not a function. It's just a word I want to define, but not have to define in-line everywhere I use it. I basically want to write a glossary file and be able to link to definitions from that glossary in my JSDoc.
Ideally this would also be in a way the VS Code picks it up and lets someone navigate to that definition on hover.
Yes there is. When you run jsdoc to generate your documentation, you can pass it any filetype you wish. A standard practice is to create one or more *.jsdoc files which contain doclet comments (those that begin with /**) to describe features you expect to use elsewhere in your code. For instance:
// filename: grokelation.jsdoc
/**
* #module grokelates
*/
/**
* #name Grokelate
* #memberof module:grokelates
* #description
* Here is the description of the grokelation process.
*
* #example
* var g = new Grokelate(opts);
*/
Then, when you wish to reference this new object elsewhere in your documentation, simply use its long name module:grokelates~Grokelate where you can consider the ~ glyph to mean "member of".
In your example above, you'd say {#link module:grokelates~Grokelate}.
Related
I am a bit baffled because some files in Linux kernel (notably include/linux/list.h) and all files is ccan have documentation comments resembling Doxygen ones (i.e.: enclosed in `/** ... */), but semantically different and Doxygen (at least with pretty standard options) chokes on them.
Typical example is (linux list.h):
/**
* INIT_LIST_HEAD - Initialize a list_head structure
* #list: list_head structure to be initialized.
*
* Initializes the list_head to point to itself. If it is a list header,
* the result is an empty list.
*/
static inline void INIT_LIST_HEAD(struct list_head *list)
{
WRITE_ONCE(list->next, list);
list->prev = list;
}
where I (and also Doxygen, I suspect) would have expected something like:
/**
* INIT_LIST_HEAD - Initialize a list_head structure
*
* Initializes the list_head to point to itself. If it is a list header,
* the result is an empty list.
*
* #param list list_head structure to be initialized.
*/
static inline void INIT_LIST_HEAD(struct list_head *list)
{
WRITE_ONCE(list->next, list);
list->prev = list;
}
Is this kind of documentation supposed to be digested by some other tool or am I simply missing some obscure (to me) parameter/configuration?
UPDATE:
I am aware (as #albert commented) that order is unimportant; what I find disconcerting is usage of #variable_name: doc string instead of #param variable_name doc string.
Trying to use Doxygen without specific care results in:
list.h:195: warning: Found unknown command '#list'
I could find no Doxyfile in either project and that's one reason why I suspect they're using some other tool, but I cannot divine what and how they're using it.
I will try to contact ccan maintainer directly.
Can Doxygen build references such as a link is defined somewhere only once and any reference to it gets the corresponding redirection?
This would allow for \see commands pointing to the right resource without the need of duplicating the URL everywhere in the code, while making it easy to change said link if need be.
Generated docs would look a little bit like this:
mainpage.md
Useful links are defined here
A guide to something
Datasheet of something
source.c File Reference
(...)
See also
A guide to something //points to URL defined in mainfile.md
[EDIT]
Thanks to #albert in the comments, I've managed to do just that using \snippetdoc, however any text after the block-id makes doxygen unable to render the snippet.
Working example:
Knowing that my links are defined in the docs/mainpage.dox file like this:
[url_to_link1]
Link description
[url_to_link1]
[url_to_link2]
Link description
[url_to_link2]
This works:
/**
* \file
* \section links "Useful Links"
* - \snippetdoc docs/mainpage.dox url_to_link1
* - \snippetdoc docs/mainpage.dox url_to_link2
*/
This doesn't:
/**
* \file
* \brief Some function definition
* \see API reference on specific subject (more info: \snippetdoc docs/mainpage.dox url_to_link1)
*/
Doxygen version is 1.8.14
As indicated in the question and comments a solution for this problem lies in the command \snippetdoc, an alternative is to define an ALIAS (in Doxyfile the doxygen configuration file) for the reference and use the defined command / alias on the required places.
As indicated by OP possible solutions by means of \snippetdoc are:
/**
* \file
* \section links "Useful Links"
* - \snippetdoc docs/mainpage.dox url_to_link1
* - \snippetdoc docs/mainpage.dox url_to_link2
*/
The following version does not work as indicated by OP:
/**
* \file
* \brief Some function definition
* \see API reference on specific subject (more info: \snippetdoc docs/mainpage.dox url_to_link1)
*/
The problem is that the definition of \snippetdoc is \snippetdoc <file-name> ( block_id ) where (block_id) means that it reads till the end of the line (see the doxygen documentation) and thus the closing ) is part of the block_id and cannot be resolved.
A possible better implementation could be <block_id> so that block_id is a single word. Problem for this is that this that it might break existing documentation where e.g. spaces or dots are used in the block_id.
There are a number of solutions for this problem:
1) Define the closing ) as part of the block_id (in the not working version):
[url_to_link1)]
Link description)
[url_to_link1)]
2) Place the closing ) on the next line (definition can stay as in the question):
/**
* \file
* \brief Some function definition
* \see API reference on specific subject (more info: \snippetdoc docs/mainpage.dox url_to_link1
* )
*/
3) Define 2 definitions:
[url_to_link1)]
Link description)
[url_to_link1)]
[url_to_link1]
Link description
[url_to_link1]
I general solution 2) is the preferred solution as the solution. All text following the block_id has to be on the next line.
I can't get the google sheets autocomplete to show my custom function even when I use Google's version (see below). I have the jsdoc info correctly formatted, but it still doesn't show up. I'm sure I'm just overlooking something stupid, but I can't find it. So what am I missing?
Google's demo code:
/**
* Multiplies the input value by 2.
*
* #param {number} input The value to multiply.
* #customfunction
*/
function double(input) {
return input * 2;
}
BTW, I'm using Chrome to develop my custom functions. Also, my function works, just no autocomplete. All the built-in functions autocomplete works.
Thanks in advance for the help!
Brad
I managed to get the custom function autocomplete working yesterday. It seems to only work with container-bound scripts, so any JSDoc info inside a script being used as a library will not come across. To verify it works, I did the following:
Create new Google Sheet
Open Script Editor
Enter the following in the script:
/**
* Returns amount multiplied by itself.
*
* #param {Number} amount The amount to be multiplied by itself.
* #return {Number} The amount multiplied by itself.
* #customfunction
*/
function test(amount) {
return amount*amount;
}
Then, when entering =test into a cell in the spreadsheet, the information above the function appears in the autocomplete hint, like any other built-in spreadsheet function.
I'm trying to generate a doxygen document where I have two documentation instances for functions. One describes the usage(interface) of the functions that get pulled from the function header in the .h file and the other describes implementation of the function that gets pulled from the .c file. I basically want to describe the same function in two different ways based on where the file that the description came from(.h or .c). I thought this would help the usability of the document since you can easily ignore the implementation details if you only care about how to use the functions. My best attempt was to try to add the .h and the .c files to separate groups like this.
example.h
/**
* #defgroup exampleInterface Example Interface
* #{
*/
/**
* This is the header file so I describe how to use this function
* #param arg
* #returns something
*/
int someFunction(int arg);
/**
* #}
*/
example .c
/**
* #defgroup exampleImpl Example Implementation
* #{
*/
/**
* This is the .c file so I describe how this function is implemented.
*/
int someFunction(int arg)
{
... Some code ...
}
/**
* #}
*/
The result was that the function header descriptions were still combined. Is there anyway to accomplish this in doxygen? Maybe there is another way I should look at this problem.
Thanks.
A possible hack you could try is to use the #internal command for the implementation which would mean you would run doxygen twice: once without the internal (for the external definitions) and the other with the inernal which would combine them.
I am trying to figure out if there is a way to create a custom tag using Doxygen. I did find the ALIAS configuration file option but that does not do exactly what I need. Basically in my code I want to be able to write something like
/// \req Requirement #322 - blah blah
And then have Doxygen create a list like it does for \bug and \todo commands for lines that have this custom tag. Is this possible with Doxygen?
The generalization of \bug and \todo is \xrefitem.
The solution I suggest is:
in Doxyfile:
ALIASES += "req=\xrefitem req \"Requirement\" \"Requirements\" "
in documented code:
/// \req #42 - The system shall work in any situation
Thanks mouviciel! I have adopted your solution and extended it for my purposes.
The text below goes into my Doxyfile:
ALIASES += req{1}="\ref SRTX_\1 \"SRTX-\1\" "
ALIASES += satisfy{1}="\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1"
ALIASES += verify{1}="\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1"
Where SRTX is the name of my project and is used as a prefix to requirements.
Then I create a file called Requirements.dox that provides a link between the requirement id and a URL for the requirement in my requirements management tool (an issue tracker in my case).
/**
#page Requirements
#section Build1
#anchor SRTX_1113
SRTX-1113
#anchor SRTX_1114
SRTX-1114
*/
One could also put the text of the requirement in the anchor tag if you didn't need to link to an external source.
In my code I have:
/**
* This is the basic executive that schedules processes.
* #satisfy{#req{1114}}
*/
class Scheduler: public Process
{
...
}
And in my tests I put:
/**
* Provide a number of tests for process scheduling.
* #verify{#req{1114}}
*/
class Scheduler_ut : public CppUnit::TestFixture
{
...
}
This gives me related pages for Requirements, Requirements Implementation, and Requirements Verification. It also provides Satisfies requirement and Verifies requirements sections in the class description (or function -- wherever you put the tag).
Combining the two answers above, you can have a single clean requirement tag that will build a cross-reference table, and, also provide a direct link to the requirement repo in your docs:
Doxygen CONFIG file:
ALIASES = "requirement{1}=#xrefitem requirement \"Requirements\" \"Requirements Traceability\" \1"
Source code:
#requirement{REQ-123} Brief textual summary of this requirement item
This will render in the documentation as:
Requirements:
REQ-123 Brief textual summary of this requirement item