Looking at AST explorer, JSDoc comments are parsed into a nice domain specific AST. Example:
https://astexplorer.net/#/gist/72b1e9eb9b8e91a5bcf0af8eb281788c/c6944194a73654cf234ad79a004558ca8e67e286
So the following code:
/**
* #mytag Test comment
*/
const X = 1
Looks something like this parsed:
VariableStatement
|- declarationList... (irrelevant)
|- jsDoc
|- JSDocComment
|- tags
|-JSDocCommentTag
Now in the package #babel/types there are no factories for jsDoc nodes also no ast node has a jsDoc field like on astexplorer.net
What is the situation with this? I'd like to construct ast nodes with JSDoc tags. Does typings+factories live in separate package?
The ASTExplorer link has the Typescript parser enabled, not Babel's. Typescript parses JSDoc comments, because Typescript lets you use JSDoc annotations for types.
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}.
I'm going to write documentation for some script API bindings (Lua actually), so there's no source code at all. How can I do that?
I've tried to write bare doxygen like this:
\page My API document
\class BindedClassA
\brief descriptions on it
\var member1
\brief ssssssss
\fn bindedMethod1(arg1, arg2)
\brief xxxxxxx
\param arg1 yyyyyyy
\param arg2 zzzzzzz
\return wwwwww
It won't work at all. Actually it seems you must specify a language for every doxygen input file via EXTENSION_MAPPING.
Then I tried to put things in a fake C++ file that have no source code but only comments:
/**
*\page My API document
**/
/**
*\class BindedClassA
*\brief descriptions on it
**/
/**
*\var member1
*\brief ssssssss
**/
/**
*\fn bindedMethod1(arg1, arg2)
*\brief xxxxxxx
*\param arg1 yyyyyyy
*\param arg2 zzzzzzz
*\return wwwwww
**/
It generates document for BindedClassA, but only have brief description, no members o method documents were generated.
It seems the structure in source code plays critical role for Doxygen working properly, but I have no source at all.
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.
I'm trying to document a Javascript file with JSDoc(3) like so:
/** 1 if gnome-bluetooth is available, 0 otherwise
* #type {boolean}
* #const
*/
const HAVE_BLUETOOTH = #HAVE_BLUETOOTH#;
Now the file (called config.js.in) is not on its own valid Javascript; the file gets run through a Makefile which substitutes an appropriate value for #HAVE_BLUETOOTH#.
When I try to run JSdoc on this, it (understandably) balks because of the syntax error in the file.
Is there some way to tell JSDoc to ignore all code in this file but simply take into account the annotations? (I might have to add #name tags to each doclet to completely separate the documentation from the code; that's fine).
Something like:
/** 1 if gnome-bluetooth is available, 0 otherwise
* #name HAVE_BLUETOOTH
* #type {boolean}
* #const
*/
/** #ignore */ // somehow ignore from here onwards
const HAVE_BLUETOOTH = #HAVE_BLUETOOTH#;
/** !#ignore */ // somehow don't ignore from here onwards (although I'd be happy
// to ignore the entire file)
I'd prefer not to modify the code part of the file, if possible (I'm adding documentation to an existing project). For example, I could probably get around it with
const HAVE_BLUETOOTH = parseInt('#HAVE_BLUETOOTH#', 10);
which would make the file have valid JS syntax again so that the parser doesn't complain, but this also means I'm modifying the code of the original file which I want to avoid (I prefer to just add documentation).
cheers
My case is similar because I use JSDoc to comment my .less and .css file. When I running JSDoc on set of file, I have the same issue.
So, I resolve my problem (with JSDoc 3.3.3) with the commentsOnly JSDoc plugin
https://github.com/jsdoc3/jsdoc/blob/master/plugins/commentsOnly.js
I have create this config.json:
{
"source": {
"includePattern": ".+\\.(css|less)?$"
},
"plugins": [
"plugin/commentsOnly"
]
}
with the commentsOnly.js file into a plugin/ directory (consider plugin/ and config.json are in same folder) and in this folder I execute the following CLI command:
jsdoc -c ./config.json ./assets/stylesheets/common.less
And it's work ! There are no reason this do not work with your files.
Hope I help you ;)
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