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.
Related
I am a newbie to phpDocumentor, although I have extensively used JavaDoc in the past.
To start, I created the following test file a.php:
<?php
/**
* XYZ file-level comment.
*/
/**
* XYZ global variable comment.
*
* #var int
*/
$var = 123;
/**
* XYZ constant comment.
*
* #var boolean
*/
const DO_IT = false;
?>
And then I ran phpDocumentor v3.0.0 using the following commandline:
php D:\phpDocumentor\phpDocumentor.phar
The resulting documentation has the following issues - see a screenshot here:
Neither file-level comment nor global variable $var are present in the generated HTML.
For constant DO_IT, the first letter of the default value is missing ('alse').
Any idea what might I be doing wrong? Thanks!
I added JSDoc comments above functions in my code:
/**
* Repeat <tt>str</tt> several times.
* #param {string} str The string to repeat.
* #param {number} [times=1] How many times to repeat the string.
* #returns {string}
*/
When I hover on invocation of such function or browse through I would like Visual Studio to render documentation above my call like this:
or this
Is this is possible?
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 *).