The problem
I have a documentation split into two different groups :
API, intended for regular users, with only safe functions.
Low level API, intended for more confident users.
I added a #warning directive into my Low level API group definition, stating that all member of the group shall be used with care.
I would like this warning to be displayed in the description of every member of the group, so even if users reach member through links and so on, they are warned.
Is there a way to do that without manually adding the #warning to every members of the group, and instead apply per group/per file warning ?
More information
My version of Doxygen is 1.8.17, however I should be able to upgrade it if required.
I can edit all files of the project, as well as the Doxygen configuration file.
Example of wanted behavior
I want to achieve following behavior :
/** #addtogroup low_level_api
#warning This is a warning I want to display in every member of the group
#{
*/
/** #brief some function of my example
#warning This is a warning I want to display in every member of the group
*/
void some_group_member()
/** #brief another function of my example
#warning This is a warning I want to display in every member of the group
*/
void some_group_member()
/**
#}
*/
Without needing to copy-paste the warning in every member of the group, as an hypothetical :
/** #addtogroup low_level_api
#warning_to_all This is a warning I want to display in every member of the group
#{
*/
/** #brief some function of my example
*/
void some_group_member()
/** #brief another function of my example
*/
void some_group_member()
/**
#}
*/
Of course, #warning_to_all directive does not exists, so I need to find an equivalent of this, even if it is a more general and "rough" solution than propagating a warning, as for example displaying the group description in every member description.
There is no real grouping in the sense as OP wants of warnings (as far as I know. A solution might be to use the \snippet{doc} command like:
/** #addtogroup low_level_api
\snippet{doc} this snip
#{
*/
/** #brief some function of my example
\snippet{doc} this snip
#warning This is a warning I want to display in every member of the group
*/
void some_group_member();
/** #brief another function of my example
\snippet{doc} this snip
#warning This is a warning I want to display in every member of the group
*/
void some_group_member1();
/**
#}
*/
/*
[snip]
#warning This is a general warning I want to display in every member of the group
[snip]
*/
Related
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}.
In IntelliJ IDEA 2016.3.3 the comment code is formatted like this:
/** ***********************/
/* BACKEND CONFIGURATION */
/** ***********************/
Notice the space after /**
Is it possible to remove that space?
= UPDATE =
To be more precise, I am using these comments solely in-line to (same as I did in java) mark important blocks if algorithm is lengthy.
I just have tested this
/************************
* Test text
* #param jobConfig
*/
class AutoencoderTrainingJob(val jobConfig: Sometype
scaladoc is being displayed by IntelliJ Quick Documentation. The additional asterisks just show up as part of class descirption
I've noticed strange behavior with doxygen, where function documentation will be applied to multiple functions. eg:
The example below works as expected (only function_a is documented).
However using groups causes changed behavior.
void function_a(void) {}
/** Document function B */
void function_b(void) {}
void function_c(void) {}
With a group however the doc-string Document function B is applied to all 3 functions.
/** \name My ABC Functions
* \{ */
void function_a(void) {}
/** Document function B */
void function_b(void) {}
void function_c(void) {}
/** \} */
Is there a way to avoid this?Besides having doc-strings for all functions in the group.
Edit, using Doxygen version 1.8.11
This was caused by DISTRIBUTE_GROUP_DOC being enabled in the configuration on the project I was contributing to.
This is disabled by default, and disabling resolved the issue.
See:
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES then doxygen will reuse the documentation of the first
# member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly.
# The default value is: NO.
DISTRIBUTE_GROUP_DOC = YES
Using Doxygen version 1.8.4:
When AUTOLINK_SUPPORT = NO in the configuration file, the HTML See Also section references generated by \sa (or #see) are not active links to the referenced method. When AUTOLINK_SUPPORT = YES the \sa references are active links as expected.
This seems to be a relatively recent change to doxygen behaviour: I've been using AUTOLINK_SUPPORT = NO for years to avoid having to mark all the words in the description text that would otherwise result in undesired automatic links with a '%' character, and the See Also references had remained active links.
Is there a known workaround that enables \sa references to remain active links while still having global AUTOLINK_SUPPORT disabled?
Here is a trivial test file:
/** The Fooy class.
*/
class Fooy
{
public:
/** foo
The alternative is {#link bar(int, int)const the bar method}
#param value A value.
#return The value incremented.
#see bar(int, int)const
*/
int foo (const int value) const;
/** bar
The alternative is {#link foo(const int)const the foo method}
#param value A value.
#param number A number.
#return The value plus the number.
#see foo(const int)const
*/
int bar (int value, int number) const;
};
Using the auto-generated Doxyfile (doxygen -g) doxygen version 1.8.8 produces, without any warnings, the expected HTML results: The {#link bar(int, int)const the bar method} syntax results in a link named "the bar method" (and likewise for the other #link), and the #see references result in the expected links having the method signatures.
If the Doxyfile is changed so AUTOLINK_SUPPORT = NO doxygen now produces HTML in which the #see signatures are no longer links, but is otherwise the same.
If " the bar method" is removed from the first #link command doxygen outputs -
Fooy.hh:9: warning: unable to resolve link to `bar(int, int)' for \link command
And the resulting HTML has the single word "const" as the link to the html/classFooy.html file instead of the method signature and correct link. However, if the single space is removed after the comma in the argument list of the method signature the warning disappears and the link is now correct with the full signature text. Note that the space character
in the foo argument list of the second #link command must remain to have a correct signature, so removing the text " the foo method" from the command will always result in an incorrect parsing by doxygen. Restoring AUTOLINK_SUPPORT = YES does not change this behaviour. This suggests a flaw in the doxygen parser.
Back to the initial issue of getting the #see references to be links in the HTML output when AUTOLINK_SUPPORT = NO in the Doxyfile. Putting the method signatures in the #see commands inside {#link ...} wrappers fails as described above (only if the method signature has no space character does it work correctly). If the wrappers are replaced with the new #link ... #endlink syntax (and the new syntax used with the other {#link ...} commands) then the HTML output from doxygen is the expected results with full method signatures and correct links.
So the answer to this problem is that doxygen is not backwards compatible with previous in-code command syntax. Unless some workaround is known, all existing code files must be edited to accommodate the changes to the doxygen parser.
Sigh.
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.