In non-Doxygen comments, I often have:
/* Lorem ipsum etc.
*
* Notes:
* - A first note.
* - Some other note note.
*/
But with Doxygen, I have #note (or \note), not #notes). So, should I use multiple #notes, or do I put all notes under the same #note?
The #note command results in a paragraph which format can be customized in the CSS file or in the style file when using Latex. So you can just use the markups like in a "normal" text:
/**
* Bla bla...
*
* #note Even in a note you can use markups:
* - Your first note
* - Youre second note
*
* The note section ends with an empty line or the end of the comment.
*/
You can do it either way; it's really a question of style/preference.
As you pointed out, Doxygen has the #note command, but not #notes. You can create your own command for #notes by editing the Doxyfile, and modifying the ALIASES = tag to read
ALIASES = "notes=#par Notes:\n"
With this, you can put the command #notes in the documentation, which will result in a user-defined paragraph with the heading
Notes:
As pointed out in the Doxygen documentation for the ALIAS tag, you can put \n's in the value part of an alias to insert newlines.
Related
As Markup Formatting Reference states, you can use *,+ or - characters as prefixes for markup keywords. For example, take a look at Parameter:
Now, when I try to use *, markup doesn't work:
/**
* Parameter piece: A piece to validate.
* Parameter matchBlock: Called only if necessary.
*/
init(piece: MSPiece?, matchBlock: MatchBlock) { ... }
The above code results in:
But if we put + or - instead of *,
/**
+ Parameter piece: A piece to validate.
- Parameter matchBlock: Called only if necessary.
*/
init(piece: MSPiece?, matchBlock: MatchBlock) { ... }
The documentation will be correct:
Why doesn't * work? It would be actually cool to use an asterisk because /** */ comment stats and ends with asterisk and it would be really neat.
It was a bug and it's fixed in Xcode 10.0.
Is it possible to order the groups (i.e. Modules) listing in Doxygen PDF output?
For example if I build my current C project, the group for commands is listed in the resulting PDF before status as it follows a alphabetical ordering by default whereas I would like status to be listed before commands.
I tried changing the group name and leaving the tag name the same for the module title, but this did not seem to have any effect, e.g.
/** #defgroup g1 Status */ = /** #defgroup status Status */
Thanks
You can set your group order in a block of #defgroup at the first of the code page or befor the first group definition. You don't need a group scope for the defgroup part.
/**
* #defgroup A_group Group of Macro A
* #defgroup B_group Group of Macro B
* #defgroup C_group Group of Functions
*/
Than define each group with #ingroup in order your code is needed.
/**
* #ingoup b_group
* #{
*/
...
/** #} */
...
/**
* #ingroup a_group
* #{
*/
...
/** #} */
...
/**
* #ingroup c_group
* #{
*/
...
/** #} */
I used #Cheeseminer's advice here and fiddled with the settings so that only group documentation is shown, then added the files only individually via the INPUT command, listing them in the order I would like.
Downside is that every time I add a new file to my code-base I have to remember to add it to the INPUT command :\
Create a file that has the groups in the order you want, then put that first in the input line along with . so:
file index.c:
/** #addtogroup status
#addtogroup commands
*/
and in the INPUT var in .doxygen
INPUT = index.c .
This will sort the items as you want, but not add any new symbols, and you can still use the default gathering of source files without worrying about order.
I don't know about pdf output, but for html output it was SORT_GROUP_NAMES = YES in the doxygen config file which solved the issue for me.
https://www.doxygen.nl/manual/config.html#cfg_sort_group_names
I tried to write like this
{ "keys": ["ctrl+shift+;"], "command": { "characters": "/**#var*/", "block": true} }
But seem it totally not achieving what the simplest thing I try to do.
What I want the shortcut to do is that once triggered, I wish to enter text formatted like this
/**
*#var
*/
Does anyone know how to define such custom shortcut?
Thank you very much!
There are two ways to do this, depending on what functionality you want. If all you want is to print exactly what you indicated, then create the following snippet:
<snippet>
<content><![CDATA[
/**
* #var $0
*/
]]></content>
<tabTrigger>vardoc</tabTrigger>
</snippet>
To do so, create a new file with XML syntax, paste the above exactly as shown, then save the file as Packages/User/vardoc.sublime-snippet where Packages is the directory opened when you select Preferences -> Browse Packages. To trigger the snippet, type vardoc and hit Tab. Your cursor will be positioned where the $0 is in the snippet.
This should work fine, except you'll have to type * if you need a new line, and there's nothing intelligent about it. Instead, what I'd recommend is DocBlockr, a Sublime Text plugin that auto-generates documentation for several languages, including PHP. Typing /** and hitting Tab or Enter will give you
/**
* |
*/
Where | is your cursor position (this is also a built-in Sublime feature, I believe). It can also auto-document functions. If you have
function foo(MyClass $cls,
Array $arr,
$num=42,
$val=false,
$str="sweet function, dude!") {
return $something;
}
and you place your cursor on the line above the function definition and type /** and hit Tab, you'll get
/**
* [foo description]
* #param MyClass $cls
* #param Array $arr
* #param integer $num
* #param boolean $val
* #param string $str
* #return [type]
*/
with [foo description] highlighted so you can enter your own description. Hitting Tab again will subsequently highlight MyClass, Array, etc. so you can alter them if you wish.
More to your question, you can declare a variable
var $foobar = "I love unicorns";
Placing your cursor above that declaration and entering /** Tab will give you
/**
* [$foobar description]
* #var string
*/
There are other features of DocBlockr as well, check out the link above for more details.
I hope this helps!
if I have a c header file with a doxygen comment:
/*!
* #file MyHeaderFile.h
* #brief Brief header file description
* #author Me Myself
* #date 2012.4.16
*/
This results in html like this:
This same syntax works fine in function comments:
Am I doing something wrong or is this all that is supported?
EDIT: normal function comment:
/*!
* #brief This function does things
*
* #author Me Myself
* #date 2012.4.16
*
* #returns void
*/
void MyFunctionThing(void)
{
}
Although I could not really reproduce the problem given your example, this is most likely the result of Markdown support (introduced in version 1.8.0), in particular the code blocks feature.
Options you can try to avoid/workaround this:
Set MARKDOWN_SUPPORT to NO in the config file
Indent the text in you comment block with less than 4 spaces (after the *).
I would like to know how to escape phpdoc comments within a phpdoc comment.
For example, how would I have to write this:
/**
* Some documentation...
*
* <code>
* /**
* * Example example phpdoc.
* */
* </code>
*/
Obviously above example won't work.
I tried replacing the asterisk's with *, but it will just nicely print "*"...
According to DocBlock Description details, you can, as of 1.2.0rc1, write {#*} to write */.
For example:
/**
* Simple DocBlock with a code example containing a docblock
*
* <code>
* /**
* * My sample DocBlock in code
* {#*}
* </code>
*/
You need to use #example.
Add the following lines after the tag </code>
#example /path/to/example.php How to use this function
#example anotherexample.inc This example is in the "examples" subdirectory
You can find more info here.
So you apparently need to have the example code in a separate file too.