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.
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.
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}.
i use doxygen 1.8.15 for the first time.
I generate Doxyfile by doxygen -g and try to create documentation just by doxygen.
Among other i have in the base directory test.cpp looking like this:
/**
* This is a test. doc for an enum
*/
enum Test {
/**
* doc for an item
*/
SomeItem
};
I expect the html output in html/index.html but this is essentially an empty site.
The following is an extract of the output:
Parsing files
Preprocessing /home/ernst/Ankrit/Software/Products/Recon/recon/Mbed/main.cpp...
Parsing file /home/ernst/Ankrit/Software/Products/Recon/recon/Mbed/main.cpp...
Reading /home/ernst/Ankrit/Software/Products/Recon/recon/Mbed/mbed_settings.py...
Parsing file /home/ernst/Ankrit/Software/Products/Recon/recon/Mbed/mbed_settings.py...
Preprocessing /home/ernst/Ankrit/Software/Products/Recon/recon/Mbed/test.cpp...
Parsing file /home/ernst/Ankrit/Software/Products/Recon/recon/Mbed/test.cpp...
Building group list...
As you can see test.cpp is inside. But in the results nothing on cpp shows up, only mbed_settings.
What did i do wrong?
When e.g. cpp code doxygen has the "habit" of not finding some information when no corresponding .h file is present.
With the aid of the \file command this problem can be overcome, so the code:
/// \file
/**
* This is a test. doc for an enum
*/
enum Test {
/**
* doc for an item
*/
SomeItem
};
gives the requested result.
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 want to use Play Templates to generate source code for a programming language.
I'd like to add support for a custom format to the template engine as per Play's documentation. But I do not understand:
1) Where to specify a new file extension? templatesTypes += ("code" -> "some.lang.LangFormat")
in build.sbt?
2) how to stop Play from escaping HTML characters and adding blank lines
Has anyone got experience with Play custom template formats?
If possible please provide links to examples.
1) The extension in your example would "code", so for example, for a python template generator, you would do:
templateTypes += ("py" -> "some.python.PythonFormat")
2) The thing that escapes HTML characters is the some.lang.LangFormat class, which has to implement the play.api.template.Format class. This has the following two methods:
/**
* A template format defines how to properly integrate content for a type `T` (e.g. to prevent cross-site scripting attacks)
* #tparam T The underlying type that this format applies to.
*/
trait Format[T <: Appendable[T]] {
type Appendable = T
/**
* Integrate `text` without performing any escaping process.
* #param text Text to integrate
*/
def raw(text: String): T
/**
* Integrate `text` after escaping special characters. e.g. for HTML, “<” becomes “<”
* #param text Text to integrate
*/
def escape(text: String): T
}
So you can just make escape delegate to raw if you don't want to do any escaping.
As far as controlling line breaks goes, this is an aspect of the templates themselves, if you put line breaks in a template, they will appear in the result. So for example:
#if(foo) {
#bar
}
Will have line breaks, whereas:
#if(foo) {#bar}
won't.