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!
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.
I am using Eclipse Juno and PDT. With the PHP Formatter i am formatting my code. I have created an own formatter preset based on the PSR-2 template.
Problem
I cant find any configuration option to keep the whitespaces in #param phpDoc comments.
Before code formatter:
/**
*
* #param string $sName name value
* #param mixed $sValueWithLongName value
*/
After code formatter:
/**
*
* #param string $sName name value
* #param mixed $sValueWithLongName value
*/
How can i keep the whitespaces without using the #formatter:off tags?
On juno (PDT 3.1) you can't.
You need PDT 3.3.2. In option's you'll find "disable phpdoc formatting".
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.