I am writing API doc comments and would like to include code examples in a comment block with comments included in this same block. I have change the font color for the block comments themselves but not for the comments in the comment.
Is there a way to edit the colors/text-decorations of these? I find it too dark and difficult to read. This happens with every theme I have installed.
This is not related to VS Code, you can highlight an example of the code usage using JSDoc tags. In your instance you're looking for #example:
/**
* #example
* myFunc('calling my func');
*/
function myFunc(args) {
}
And you will see your code sample highlighted in VS Code:
Related
I have documented my code with doxygen. The generated docs consist of:
a page with the documentation as I put between /** ... */, and
a page with the source-code itself (without the documentation between /** ... */).
Now my question is: Is there a way to generate links such that one can reach the page with the source code opened on the relevant line directly from the documentation?
To show visually what I would like to obtain:
I would like to have a button "Go to source" (shown in red, decorated with an arrow just for here).
Which would land me on the right line of the source code (possibly with a highlight, as shown here).
The following option does exactly that:
SOURCE_BROWSER = YES
Thanks #albert!
I have some source code (STM32 Peripherial Lib) with existing doxygen parameters which my Doxygen Builds without Problems.
For my project I want to generate a document with all functions in each file and a specific information which I want to add to the functions. But I want to keep the old informations for another doxygen configuration.
Is that possible?
I already added this for testing:
\ifnot "SECTION_DEFINE"
<normal Doxygen Parameters from original Source Code>
\elsif "SECTION_DEFINE"
#brief Function Check TODO
\endif
With this I could deactivate the existing documentation, but I need to write this \ifnot \elsif \endif to every function.
Can I just declare a Tag and only generate the documentation for this specific tag?
Kind regards
Andi
You may create a "related page" where only your additional information will be displayed with the \xrefitem command. As \xrefitem will also create a special text section within your original documentation you may want to combine it with your original idea of using section labels and conditional documentation. To top this concept off, use aliases in order to make your documentation more readable.
Consider this example code:
/** ST documentation
* foobar
* \exclusive for andi's function \endif
*/
void andreas(void);
/** ST documentation
* foobar
* \exclusive for beni's function \endif
*/
void benjamin(void);
You may use this alias in your Doxyfile: exclusive=\if SECTION_DEFINE \xrefitem viparea "Exclusive" "VIPs".
As long as SECTION_DEFINE is not defined, the "exclusive" information will not be included in your documentation. As soon as this section is defined, a "related page" (here: viparea.html) is created in your HTML documentation containing your documented items (here: andreas and benjamin) with the exclusive paragraph behind the command. The result:
Which formatter does Visual Code use? I read somewhere it uses jsbeautifier so I tried adding a compatible ignore comment to my .ejs template, but it doesn't work.
As far as I know, there is no way to do this without an extension.
However, you have full control of the formatting if you use this extension. It also uses js-beautify, but it adds configuration.
As specified in the js-beautify docs, the "preserve" directive only works in javascript sections. I have tested this in the script tag of an ejs file and formatting the document does NOT change the indentation of the console.log statement. This worked without changing any settings at all, actually. I simply installed the extension, saved this file as index.ejs and observed that vscode had the language mode set to html.
My test page
// These comments DON'T work because they aren't in a javascript section of the code
/* beautify preserve:start */
<h1><%= title %></h1>
/* beautify preserve:end */
<ul>
</ul>
<script>
function log() {
// Without the beautify comments, format document will move console.log
// to align with this
/* beautify preserve:start */
console.log('hello');
/* beautify preserve:end */
}
</script>
I'd like to know what's the syntax or the language used to format the code templates in netbeans ide. I mean, in the default templates I can see things like;
while (${EXP default="exp"})
{
${selection line}${cursor}
}
And:
// <editor-fold defaultstate="collapsed" desc="${comment}">
${selection}${cursor}// </editor-fold>
And I experimented and did this:
int ${IDX newVarName default="loop"};
for (${IDX} = 0; ${IDX} < ${SIZE int default="size"}; ${IDX}++)
{
${cursor}
}
And it works but I don't really know where the "${IDX}" or the "${SIZE int default="size"}" or the "${selection}${cursor}" comes from and what other statements can I use to format my templates.
Is this some scripting or programming language?
Where can I find this information?
I think Netbeans uses the template engine Freemarker for this. So all variables (= ${...}) are filled in by Netbeans at the time you use the template.
Unfortunately I don't have a full list of all default variables / methods you can use, but here are two of them listed:
${cursor}:
defines a position where the caret will be located after the editing
of the code template values finishes.
${selection}:
defines a position for pasting the content of the editor selection.
This is used by so-called 'selection templates' that appear as hints
whenever the user selects some text in the editor.
See here: http://wiki.netbeans.org/Java_EditorUsersGuide#How_to_use_Code_Templates
${IDX} looks like a custom variable you use.
See also:
- Code Assistance in the NetBeans IDE Java Editor: A Reference Guide (Code Template)
- Code Templates in NetBeans IDE for PHP
How_to_use_Code_Templates pretty much covers everything there is.
Looking at CodeTemplateParameter.java shows there is another hint called "completionInvoke" which requests showing of the code completion popup for the currently focused text component, but that is all.
Is is possible to show the source code being commented with Doxygen?
I have tried the following:
if (u[index] == ']') /**< Detailed description after the member */
and only got the following result:
< Detailed description after the member
Is there any way to force Doxygen to show the code snippet along with the comment?
If you want to show a code snippet and not from the source code itself, use #code, #endcode to enclose a code snippet within the class/method documentation.
No, but you can configure doxygen to include a source browser that contains the code, and put links from the generated documentation to the source code.