I just downloaded complete source code of PHP from php.net (PHP 5.4.0 [tar.bz2]).
They are often using three curly brackets together as given below (The following code snippet extracted form ext/ctype/ctype.c.)
/* {{{ proto bool ctype_digit(mixed c)
Checks for numeric character(s) */
static PHP_FUNCTION(ctype_digit)
{
CTYPE(isdigit);
}
/* }}} */
Does anyone have the idea why they are using these three curly brackets together?
They are vim fold markers, they make it easy to collapse and expand the text inbetween the triple curly braces in vim, in the example shown alternating between:
...
/* {{{ proto bool ctype_digit(mixed c)
Checks for numeric character(s) */
static PHP_FUNCTION(ctype_digit)
{
CTYPE(isdigit);
}
/* }}} */
...
and just
...
/* {{{ proto bool ctype_digit(mixed c)
...
If you look at the end of the file where you find them, you'll often find a block like this:
/*
* Local variables:
* tab-width: 4
* c-basic-offset: 4
* End:
* vim600: sw=4 ts=4 fdm=marker
* vim<600: sw=4 ts=4
*/
Which is another more-obvious indicator that these comments relate to vim.
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 want to automatically generate block comments for documentation using vim.
Something like:
/**
* comment
*/
are there any plugins for this?
Vim has this functionality built-in. See :help format-comments for details. Basically if you have filetype plugin on in your ~/.vimrc and are using a bracket language (like C, C++, Java, javascript, etc.), you can type /**<cr> and it will expand to:
/**
* _
where _ is the cursor position. When you're done with the comment block just hit / to end it.
A low-budget way of simplifying a Vimmer's life with C- or Java-style block comments is to add the following mapping to .vimrc.
autocmd FileType c,java inoreabbrev <buffer> /** /**<CR>/<Up>
That way, whenever you type /**<Enter> in your C or Java source it will be expanded to the following, with the cursor at _:
/**
* _
*/
Edit: As #Conner mentioned, you need to have filetype plugin indent on in your vimrc to make this work.
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.
*/
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.