I simply wanted to know what is the most accepted way to credit yourself and describe the overall package in (preferably) the beginning of the document so other individuals viewing the code have a reference?
I would like to know the answer because of a PHP project I am working on and I believe when it is done people will view the source code. I currently have a // comment in the beginning but it seems lacking. I have seen people use block comments and add a #author and so forth, is this the accepted syntax?
Thanks.
Yes, the syntax with block comments and tags like #author and #copyright is standardized, it's called PHPDoc.
You can find a good starting reference here.
The main advantage of using this standardized way of markup for code metadata is that you can then use standardized tools like PHPDocumentor to automatically generate documentation like this. Another is that advanced IDEs like PHPStorm can parse the docblocks to provide autocomplete and other code completion functionality, and even smart refactoring tools.
You can use this style it is called PHPDoc style.
/**
* return string of content between provided
* $from and $to positions.
* if $to is not provided $from will be considered
* a string to remove.
*
* #param string $str string from select contents
* #param string $from starting point for select contents
* #param string $to ending point for select contents *
* #return string
* #author
*/
function extractor($str,$from,$to)
{
$from_pos = strpos($str,$from);
$from_pos = $from_pos + strlen($from);
$to_pos = strpos($str,$to,$from_pos);// to must be after from
$return = substr($str,$from_pos,$to_pos-$from_pos);
unset($str,$from,$to,$from_pos,$to_pos );
return $return;
}
Related
I'm playing around with PHPDoc and have realised that you can use markdown to add some formatting to a DocBlock. In particular, I notice that you can use back ticks to highlight inline code.
However, I can't seem to figure out how to add blocks of code to a DocBlock, as using 4 spaces doesn't seem to work.
I've tried using <code> and <pre> too, and whilst those tags do appear in the generated documentation, the code inside them becomes commented out with HTML comments.
For example, this DocBlock:
/**
* This is a test DocBlock
*
* <pre>
* <?php
* echo('hi');
* ?>
* </pre>
*
* #return object[] An array of objects.
*/
Generates this HTML:
<pre>
<!--?php echo('hi'); ?-->
</pre>
Where am I going wrong? How can I add a block of code to my DocBlock?
phpdocumentor uses the github variant of markdown.
The proper way to add code, is then:
/**
* This is a test DocBlock
*
* ```php
* echo('hi');
* ```
*
* #return ...
*/
The phpDocumentor manual says that for Descriptions
you can format your text according to Markdown, more specifically Github-flavoured Markdown. Using this format it is easy to make your text bold, add inline code examples or easily generate links to other sites. — Inside DocBlocks
The PSR-5 PHPDoc says for Descriptions
Any application parsing the Description is RECOMMENDED to support the Markdown mark-up language for this field so that it is possible for the author to provide formatting and a clear way of representing code examples. — Description
And that Tags
MUST support Markdown as a formatting language. Due to the nature of Markdown it is legal to start the description of the tag on the same or the subsequent line and interpret it in the same way. — Tag
Example of PHPDoc using Github-Flavoured Markdown
/**
* This is a Summary.
*
* This is a Description. It may span multiple lines
* or contain 'code' examples using the _Markdown_ markup
* language.
*
* It's very easy to make some words **bold** and other
* words *italic* with Markdown. You can even
* [link to Google!](http://google.com).
*
* Here's an example of how you can use syntax
* highlighting with GitHub Flavored Markdown:
*
* ```
* <?php
* echo "Hello, world.";
* ?>
* ```
*
* You can also simply indent your code by four spaces:
*
* <?php
* echo "Hello, world.";
* ?>
*
* #see Markdown
*
* #param int $parameter1 A parameter description.
* #param \Exception $e Another parameter description.
*
* #\Doctrine\Orm\Mapper\Entity()
*
* #return string
*/
function test($parameter1, $e)
{
...
}
I don't think you should be adding the <?php tag, I would assume it will strip it off on parsing. Seeing as phpdoc you can probably skip it alltogether.
try
* <code>
* echo('hi');
* </code>
You should be able to use:-
/**
* This is a test DocBlock
*
* <pre>
* <?php
* echo('hi');
* ?>
* </pre>
*
* #return object[] An array of objects.
*/
How to write code blocks using phpDocumentor while writing tutorials/extended documentation?
I have tried <programlisting>, it can generate the <code> tag , but it does not parse its contents.
<refentry id="{#id}">
<refnamediv>
<refname>Guide for MyApp</refname>
<refpurpose>To demonstrate ...</refpurpose>
</refnamediv>
<refsynopsisdiv>
<author>
My Name
<authorblurb>
{#link mail#mail.com My Name}
</authorblurb>
</author>
</refsynopsisdiv>
{#toc}
<refsect1 id="{#id intro}">
<title>User Guide for MyApp</title>
<para>
Some Description
</para>
<programlisting>
$some = 'code';
</programlisting>
</refsect1>
</refentry>
This is actually very easy once you know how. You just need to set the role attribute on the programlisting element.
<programlisting role="php">
$some = 'code';
</programlisting>
I couldn't find this documented anywhere, other than a brief mention in the release notes, but from looking at the code, there seem to be four roles that are supported:
php - adds PHP syntax highlighting to the content and includes a line number on every line.
tutorial - adds HTML syntax hightlighting to the content and includes a line number on every line.
xml - adds pre tags around the content, but otherwise no syntax hightlighting and no line numbers.
html - treats the content as raw HTML, so you can use whatever markup you like.
Any time you want to use angle brackets, though, you will need to escape those characters or wrap the content in a CDATA section. This even applies when you want to use raw HTML. If not, the parser will try and interpret the content as XML.
For example, a raw HTML sample would look something like this:
<programlisting role="html">
<![CDATA[
<b>This sentence will be bold.</b>
]]>
</programlisting>
Also note that all of this applies to the initial version of phpDocumentor. The new version (phpDocumentor 2) doesn't appear to support tutorials/extended documentation as far as I can tell.
I checked it and I think you can use javascriptMVC documentation tool. I thik Documentation Tool.
and a demo of it is here. and I suggest you to try this.(-:
here is an output of documentJs of javascriptMVC which is /i think the thing you want. or at least I hope.(-:
and about phpDocumentor As I said I need some explains to get what you mean but for now please check these. link1.
link2 . (if the following is the thing you want).
/** #type int This is a counter. */
$int = 0;
// there should be no docblock here
$int++;
Or:
/**
* This class acts as an example on where to position a DocBlock.
*/
class Foo
{
/** #type string|null Should contain a description if available */
protected $description = null;
/**
* This method sets a description.
*
* #param string $description A text with a maximum of 80 characters.
*
* #return void
*/
public function setDescription($description)
{
// there should be no docblock here
$this->description = $description;
}
}
Another example is to document the variable in a foreach explicitly; many IDEs use this information to help you with auto-completion:
/** #type \Sqlite3 $sqlite */
foreach($connections as $sqlite) {
// there should be no docblock here
$sqlite->open('/my/database/path');
<...>
}
You can user zend studio tool which can generate selected project documentation automatically
I'm playing around with PHPDoc and have realised that you can use markdown to add some formatting to a DocBlock. In particular, I notice that you can use back ticks to highlight inline code.
However, I can't seem to figure out how to add blocks of code to a DocBlock, as using 4 spaces doesn't seem to work.
I've tried using <code> and <pre> too, and whilst those tags do appear in the generated documentation, the code inside them becomes commented out with HTML comments.
For example, this DocBlock:
/**
* This is a test DocBlock
*
* <pre>
* <?php
* echo('hi');
* ?>
* </pre>
*
* #return object[] An array of objects.
*/
Generates this HTML:
<pre>
<!--?php echo('hi'); ?-->
</pre>
Where am I going wrong? How can I add a block of code to my DocBlock?
phpdocumentor uses the github variant of markdown.
The proper way to add code, is then:
/**
* This is a test DocBlock
*
* ```php
* echo('hi');
* ```
*
* #return ...
*/
The phpDocumentor manual says that for Descriptions
you can format your text according to Markdown, more specifically Github-flavoured Markdown. Using this format it is easy to make your text bold, add inline code examples or easily generate links to other sites. — Inside DocBlocks
The PSR-5 PHPDoc says for Descriptions
Any application parsing the Description is RECOMMENDED to support the Markdown mark-up language for this field so that it is possible for the author to provide formatting and a clear way of representing code examples. — Description
And that Tags
MUST support Markdown as a formatting language. Due to the nature of Markdown it is legal to start the description of the tag on the same or the subsequent line and interpret it in the same way. — Tag
Example of PHPDoc using Github-Flavoured Markdown
/**
* This is a Summary.
*
* This is a Description. It may span multiple lines
* or contain 'code' examples using the _Markdown_ markup
* language.
*
* It's very easy to make some words **bold** and other
* words *italic* with Markdown. You can even
* [link to Google!](http://google.com).
*
* Here's an example of how you can use syntax
* highlighting with GitHub Flavored Markdown:
*
* ```
* <?php
* echo "Hello, world.";
* ?>
* ```
*
* You can also simply indent your code by four spaces:
*
* <?php
* echo "Hello, world.";
* ?>
*
* #see Markdown
*
* #param int $parameter1 A parameter description.
* #param \Exception $e Another parameter description.
*
* #\Doctrine\Orm\Mapper\Entity()
*
* #return string
*/
function test($parameter1, $e)
{
...
}
I don't think you should be adding the <?php tag, I would assume it will strip it off on parsing. Seeing as phpdoc you can probably skip it alltogether.
try
* <code>
* echo('hi');
* </code>
You should be able to use:-
/**
* This is a test DocBlock
*
* <pre>
* <?php
* echo('hi');
* ?>
* </pre>
*
* #return object[] An array of objects.
*/
Sometimes I see php comments with '#' in front of some lines. Like #Author. Is there any particular reason for this? I cannot seem to find anything about this. I am assuming there is highly used parser that looks for '#'s.
This is most likely phpDocumentor notation, a program which parses source code (and those # comments) to auto-generate documentation. Many IDEs also provide intelligent lookup and autocomplete functionality based on these comments.
Example:
/**
* Echoes "example".
* #author Pekka
* #version 1.5
* #return void
*/
function example()
{
echo "example";
}
This is used by automatic documentation generators to create documentation from the comments. There are a few tools and formats out there:
phpDocumentor
Doxygen
HeaderDoc
To list a few.
There are lots of packages that parse source code for comments and create intricate help files in various formats (like HTML, Windows .chm files, etc.). Java, obviously, has javadoc, but there's also Doxygen and Doc-O-Matic, just to name a few.
I am trying to write a PHPDoc description and as soon as I type a dot (.) it just cuts the rest of the description in the code assistant. For example,
/**
* A boolean value indicating whether code assitant worked with dots in PHPDoc.
* As you can see, it did not work!
* #var bool
*/
public $var = false;
I only see the first line in the code assistant. How would I solve this problem?
I haven't had any luck using the Short Description and Long Description in Eclipse (Helios) - even though it should be supported.
An option if you want to increase the length of your short description is to use the <br> tag. As long as you don't include a period in your short description, you can span it over multiple lines. You can even use other tags to add a bullet list if you like.
/**
* Function to take a 10 digit phone number and<br>
* return it in North American standard format of:<br>
* <ul><li>(123) 456-7890</li></ul>
*
* #param int $phone <ul><li>up to 10 digit int for the phone number</li></ul>
* #return string <ul><li>formatted phone number</li></ul>
*/
Eclipse Helios supports most (if not all) of the DocBlock format tags listed on this web page.
phpDocumentor Tutorial: DocBlock Description Details
However, not all these tags work in all instances, and there are definitely examples in other sections of this page that do NOT work. But using these techniques can definitely make your phpDoc blocks look better.
It is likely that the code assistant logic expects that docblock descriptions exist in the "one sentence summary description, followed by a longer detailed description", and most likely only shows the summary description in popups. In Eclipse, you can tab into the code assistant popup, and the information in there expands to show everything (via scrollbars).
UPDATE:
Testing KingCrunch's exact layout of (short description to a period, blank like, additional description with/without a period, blank line, tags) in Eclipse PDT on Helios shows that the period in the first sentence does indeed prevent the popup from showing any of the description beyond the period. I even moved the secondary portion onto the same line with the first portion, and everything beyond the period still does not appear. Change it to a comma, and everything up to the next period will then appear. Well, unless there's a blank line between the comma'd line and the next line... in that case, the blank line has the same effect as a period would, blocking everything after it. I see no issue with the tags being seen and interpreted, regardless of whether or not the description pieces are visible.
I believe, therefore, that Eclipse is indeed ignoring all description beyond the first period and/or blank line that it encounters. I'm unaware of a way to disable this behavior.
ashnazg is almost right. Usually there is the "short summary". You have no empty line after that, so it assumes, that the whole block (including the tags) belongs to the summary and are cut down after the first full stop (because its a short summary ;))
Newlines after the short summary and before the tags should work.
/**
* A boolean value indicating whether code assitant worked with dots in PHPDoc.
*
* Should work ;)
*
* #var bool
*/
public $var = false;
I've found that you can display multiple sentences if you put an HTML-encoded space character (" ") after the period. For example:
/**
* Sentence One. Sentence Two.
*/
However, if you want to include line breaks in your PHPDoc comment to make it easier to read from the source code, it will only allow up to three lines. If you include any more, only the first line will be displayed. This makes complete sense because you will never ever need more than three lines. For example:
/**
* Line one.
* Line two. Another line two sentence.
* Line three.
* This fourth line being here will prevent lines 2, 3, and 4, from being displayed.
*/
Thanks for posting this question. I've been wondering if I installed PDE wrong or something.