I use the phpDocumentor 2 to describe few methods. I want to link to the official PHP documentation of a native function. I can write something like this:
/**
* #see http://php.net/manual/en/function.ucfirst.php ucfirst
*/
These don’t work:
/**
* #see ucfirst
* #see \ucfirst
*/
Is there a better way? I am looking for something like this:
/**
* #the-official-documentation-for ucfirst
*/
You have some issue with your syntax in the documentation. You should use #link instead of #see.
/**
* #see http://php.net/manual/en/function.ucfirst.php ucfirst
*/
Change your documentation code to
/**
* #link http://php.net/manual/en/function.ucfirst.php ucfirst
*/
I have tested it and is working on my editor i.e. phpStorm
Note: It only works in the functions and class names. You cannot use it on comments.
Related
I'm using phpDocumentor 2.5.0 and the below tags do not show up in the documentation (even if done one at a time):
//None of these work
* #see MyClass::someFunction()
* #see MyClass::someFunction() that does something
* #uses MyClass::someFunction()
* #uses MyClass::someFunction() to do something
* #uses MyClass
* #uses /MyClass
* #uses /MyClass::someFunction()
How do I get it to add these to the documentation?
I am not using namespaces.
I'm running phpDocumentor like this:
phpdoc -d /home/development/code_to_document/ -t /home/development/documentation
What docblock are these lines from? As long as it's a true docblock:
/**
* #see MyClass::someFunction()
*/
and the docblock is on a documentable code element (class, method, function, etc), then I would expect the tags to appear, even if neither MyClass nor MyClass::someFunction() were found in your code project.
If your test code meets these requirements, then you may have discovered a bug. I suggest at least trying several of the different output templates, to see if the missing tag behavior persists over all of them.
What I want is that when I declare a magic method with #method PHPDoc, can i use #see so that the magic method has the same PHPDoc as the method pointed via #see
Here is the code of what I have tried. But IDE did not recognize it. I am using Netbeans 7.3.1.
/**
* #method string my_method() #see _my_method()
*/
class Foo {
public __call($name, $args) {
$name = "_".$name;
$this->$name($args);
}
/**
* #return String
*/
protected _my_method() {
return "bar";
}
}
The exact parsing will depend on which IDE you're using, but the PHPDocumentor documentation for #see shows a couple of differences from your usage:
The #see tag is on its own line, not appended to the line before. #link has a separate "inline" syntax if you want to include a cross-reference inside a description ({#link http://example.com/my/bar}).
The "target" should be a fully qualified element name, not just the local method name, e.g. #see Foo::_my_method()
There is also a draft PSR to standardise the behaviour, with similar requirements.
I would like to create links to "other" methods to, and I tried #see, #link and lots of other stuff, without any helpfull results.
In phpstorm everything is yust displayed as text.
BUT:
I discovered, that you can write own html-code, so
e.g.
/**
* #method string my_method() see _my_method()
*/
class Foo {
}
would work to create links on external pages.
Unfortunally it only works for external links, and not for links to methods in your editor.
I am reading some PHP code from someone else and the file is filled comments preceeding each meathod. What does the comment #access and #var mean ?
/**
* EE Superobject
*
* #access private
* #var object
*/
private $EE;
Many Thanks !
It's an annotation used by some documentation generating tools to generate said documentation.
Specifically used by phpDocuemntor to compile documentation.
phpDocumentor tags are very similar to tags for the JavaDoc tool for Sun's Java Programming Language. Tags are only parsed if they are the first thing on a new line of a DocBlock. You may use the # character freely throughout documents as long as it does not begin a new line. An example:
/**
* tags demonstration
* #author this tag is parsed, but this #version tag is ignored
* #version 1.0 this version tag is parsed
*/
Here is a list of the standard tags:
#access
#author
#copyright
#deprecated
#example
#ignore
#internal
#link
#see
#since
#tutorial
#version
inline {#internal}}
inline {#inheritdoc}
inline {#link}
These are PHPDoc tags: http://en.wikipedia.org/wiki/PHPDoc they are used to describe certain properties of a class or function; the documentation is automatically generated from the comments above class/functions.
I'm trying to document PHP class members with Doxygen (I'm not using PHPDocs because the project involves COCOA programming, so I can use the same tool for both parts).
/**
* This is brief description.
*
* This is detailed description.
*/
private $foo;
This code gets the documentation done right, but I would like to include in the docs the type the var should handle.
I tried to use \var and \property, but then Doxigen does not generate the doc for the var.
//THIS IS NOT WORKING!
/**
* This is brief description.
*
* This is detailed description.
* \var int
*/
private $foo;
I have seen this post:
Doxygen: how to describe class member variables in php?
Seems that \var is not working in Doxyegn, but the post is a bit old and maybe there is something I can do now.
I have follow the bug comments of this feature:
https://bugzilla.gnome.org/show_bug.cgi?id=626105.
In comment number 6 a solution is proposed, adding the var name after the type.
class Mine {
/**
* Definition of variable
* #var string $var
*/
private $var = array();
}
This is working for me.
Simple workaround which generates acceptable results is to add this input filter:
INPUT_FILTER = "sed -e 's/#var\s/#see /'"
Or even better to define an alias:
ALIASES += "var=#see"
It simply replaces #var command with #see command. It is not perfect, but it is very simple and relatively bulletproof.
Small disadvantage is that the type is somewhere in the description instead of the heading. On the other side, if only few properties has type defined, it makes documentation more consistent (headings look the same).
#type works for me:
/** #type string[] */
private $csvData;
/**
* command line parameters
* #type string[]
*/
private $parameters;
can someone explain or give some examples how to use the #Category Tag the right way ? PHPDocumentator is not parsing the Tag.
How does an correct File-DocBlock and Class-DocBlock looks like ?
I don't know if this helps, but... From the manual:
The #category tag is used to organize
groups of packages together. This is
directly applicable to the
XML:DocBook/peardoc2 Converter, and
can be used by other converters. Other
Converters packaged with phpDocumentor
ignore the category, but this may
change in future versions. It is also
possible to dynamically specify
category using the -dc,
--defaultcategoryname command-line switch.
/**
* Page-Level DocBlock
* #package MyPackage
* #category mycategory
*/
/**
* #global array used for stuff
*/
function mine()
{
global $baz;
...
}
Also, here's a sample of the proper way to write PEAR code, including DocBlocks with #category.
Please post some sample code that's not parsing -- that may help in answering what's wrong.
I haven't been able to find any useful examples on how to use the #category tag. It made sense to me to use it to represent the MVC layers using that tag ie:
/**
* Layout or template
*
* #category view
*/
/**
* Database representation of the user
*
* #category model
*/
/**
* Login actions
*
* #category controller
*/
That's how I use it.