December 26, 2011 at 03:48PHP auto-documentation in NetBeans 7.01 using phpDocumentor, telling, customizing, fixing
In this article, you will gain new and old knowledge, in particular, some of them appeared quite recently in RuNet, and some were generally introduced by me directly on the spot without leaving the box office.
So you will know:
On the project I was faced with the fact that it was necessary to create normal documentation. Writing documentation separately is not the best way, the basic description of the library can also be done in the style of auto-documentation. I began to understand the issue of a miracle, in NetBeans 7.01 it is supported by PHPDoc, it is quite worthy and convenient. I was surprised by the poverty of information on this topic in the Russian segment of the network. In addition, I found several pitfalls that created problems when setting up under Windows.
If you are interested, then welcome to kat
Some do not know what auto-documentation is. Many do not use it because of the size, commenting on the code the old fashioned way in one or two lines, or do not comment at all. This many who sin and I, sometimes =). For example, among another meager description, my favorite comment is in the title of the 800-hundred line file:
Auto documentation is acar manual such a thing that allows you to write comments on the code. At the same time, inside the IDE, tips will be displayed on the code, method, function, file, etc. Further, on the basis of it, it is possible to generate complete documentation for the entire code in any HTML, PDF, XML format etc. For example, in MSDN - everything that you see in the table is created using auto-documentation by the hands of programmers. Everything else is monitored by the documentation department, who write additional chewing and examples.
In relation to the generation of documentation for PHP, there are different libraries. The most interesting ones that I found:
I decided to use PHPDocumentor. The work of this library completely satisfies me, especially after my edits in it.
- The code
- IDE Tips: we find out that the function does not obviously return a string
- Auto Documentation:
I work under windows. I have xampp - this is a very convenient thing for those who did not know, but it does not have a pre-configured PHPDocumentor. For example, pre-configured PHPUnit is. We will not blame the creators of xampp, but move on to manual configuration. No matter where they write about smart teams like PEAR, it’s better to do as mine. I’ll add on my own that I myself like to describe it in such a way that it works 100% according to the description with all absolute paths, so you can be sure that it will work if you do it like this:
- The initial
XAMPP setup is configured in the D directory: \ xampp
If what happened in D: \ xampp \ php \ PEAR \ PhpDocumentor we are not afraid and delete it. There are no smart configurations from xampp.
- Download code
We don’t think about PEAR commands, we download PHPDocumentor directly from the developer's site (links below + my correct version is there)
Unpack everything into the PEAR directory. You will need to perform some magic operations on directories: deleting unnecessary hierarchies, renaming, etc. As a result, the files and the hierarchy, in particular, the phpdoc.bat file should be in this directory: D: \ xampp \ php \ PEAR \ PhpDocumentor
- Configuring the library
Now you need to configure the library itself. To do this, go to the phpdoc.bat file.
In it we will indicate the path to our installed PHP interpreter, as well as switch the working directory.
Instead:
SET phpCli = C: \ usr \ local \ php \ cli \ php.exe
Insert:
SET phpCli = D: \ work \ rumb-software \ xampp \ php \ php.exe
CD / DD: \ xampp \ php \ PEAR \ PhpDocumentor
Attention, a pitfall!
If you will be placing XAMPP on a different drive from C: then when you select the directory (CD command) you need to add the / D argument - it took half an hour, thinking “why doesn’t it see the script?” Until I went to the kitchen to pour tea, accidentally remembering this Microsoft-magic.
- Setting up the IDE
Now we will configure the IDE to work with this extension.
To do this, go to
NetBeans 7.01> Options> PHP> PHPDoc> PhpDoc script.
Insert this line:
D: /xampp/php/PEAR/PhpDocumentor/phpdoc.bat -o HTML: frames: earthli
This line will indicate the IDE executable script and pass additional variables, so by the way they say there you can write something else as parameters. For example, you can learn from the PDF. I didn’t check, and I don’t need it.
Attention pitfall!
Slash should be a straight "/" . If you select through Browse, NetBeans will substitute a backslash.
- Now we’ll set up the path where the documentation will be saved.
Create a project like PHP, well, I won’t describe it here. Let's say I called it example-project and put it in D: / xampp / htdocs / example-project, PHP version 5.3 UTF-8 encoding
Right-click on the project
example-project> properties> PhpDoc> Target Directory
Insert the line (There is also a problem with slashes! ):
D: / xampp / htdocs / phpdoc
- Launch
After these steps, generation is available by right-clicking on the project> Generate PhpDoc.
Even in Include Path, you can connect the directory of the received documentation so that the files are visible through the IDE. In reality, this is generally not necessary, but joy =)
In the process of generation, I met several problems.
- Notices pop up
. By default, on PHP developer I have the maximum level of errors, warnings, notices and strictures. During the documentation generation, all these errors started to fall into files, basically they created their Smarty class, I express respect for the PHPDocumentor developers - they are doing well. I fixed this problem by forcibly banning it from doing in the library.
Added error_reporting (E_ERROR); in the file
D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc
- Encoding problem
I'm a little Russian and I tend to write Russian comments. Encoding issues have occurred. Here I have for example UTF-8, and in the library the generation templates were sewnother encoding iso-8859-1. The result was nonsense. Knowing how Smarty works, I fixed 3-4 files with code and registered a dynamic variable in the templates. Now the encoding of the output templates can be changed manually in the file D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc using the CHARSET constant, if necessary, the variable {$ charset} can be added to any template from the whole set, I looked at charset headers are not in all templates.
- Help from the public
I’ll add that I consider myself wrong that I didn’t post access to these fixes through the command line, but understand me correctly, I also have no rubber time, I sent the creators a proposal to make my changes to the next revision and it will be easier for them since they are architects of the entire library.
PHPDocumentor link to the library:
http://sourceforge.net/projects/phpdocu/files/
Corrected PHPDocumentor: if it does not load, contact the PM. Maybe I put my poor server again.
http://yadi.sk/d/7WnrUy5z0qE7n
Link to documentation on PhpDoc format:
http://manual.phpdoc.org/HTMLframesConverter/default/
Overseas video - setup instructions:
http://netbeans.org/kb/docs /php/screencast-phpdoc.html
The problem with slashes and what error will be in this case is described here:
pachkov.ru/?p=1222
Text for indexing by the search engine:
Error in NetBeans when creating PhpDoc (for Windows)
Error when calling the filter. The following error message was generated:
java.util.regex.PatternSyntaxException: Illegal hexadecimal escape sequence near index 10
(. *) (C: \ xampp \ htdocs \ PhpProject1 \ phpdoc / errors \ .html) (. *)
Thank you for your attention!
UPD: corrected a bunch of stupid sleepy typos
UPD2: I don’t understand who merges karma like rewrites I don’t write, and the article is purely technical and not holistic. It is necessary to remove the anonymity of the change in karma altogether, so that the public can be put on trial. Amazed and offended, but I admit that they began to lessen minus, after the introduction of a 15-point barrier.
So you will know:
- Basic information on what autodocumentation is and how it is done in PHP
- Setting up the phpDocumentor documentation generator in NetBeans 7.01
- Link to phpDocumentor library corrected by me with a list of changes made, I think some may need it right away
- Read links
On the project I was faced with the fact that it was necessary to create normal documentation. Writing documentation separately is not the best way, the basic description of the library can also be done in the style of auto-documentation. I began to understand the issue of a miracle, in NetBeans 7.01 it is supported by PHPDoc, it is quite worthy and convenient. I was surprised by the poverty of information on this topic in the Russian segment of the network. In addition, I found several pitfalls that created problems when setting up under Windows. If you are interested, then welcome to kat
Some do not know what auto-documentation is. Many do not use it because of the size, commenting on the code the old fashioned way in one or two lines, or do not comment at all. This many who sin and I, sometimes =). For example, among another meager description, my favorite comment is in the title of the 800-hundred line file:
// От себя добавлю: не знаю сколько я выпил энергетиков, что все это смог написать.
What is auto documentation in PHP
Auto documentation is a
In relation to the generation of documentation for PHP, there are different libraries. The most interesting ones that I found:
- doxygen
- PHPDocumentor
- docblox - UPD
- phpdoctor - UPD
I decided to use PHPDocumentor. The work of this library completely satisfies me, especially after my edits in it.
Examples
- The code
/**
* Складывает два числа и возвращает строковое значение
*
* @param int $arVarOne
* @param int $arVarTwo
* @return string
*/
function sum_return_string($arVarOne, $arVarTwo)
{
$result = $arVarOne + $arVarTwo;
return "$result"; // преобразование типа!!!
}
- IDE Tips: we find out that the function does not obviously return a string
- Auto Documentation:
Setting up a PHPDocumentor auto-document script
I work under windows. I have xampp - this is a very convenient thing for those who did not know, but it does not have a pre-configured PHPDocumentor. For example, pre-configured PHPUnit is. We will not blame the creators of xampp, but move on to manual configuration. No matter where they write about smart teams like PEAR, it’s better to do as mine. I’ll add on my own that I myself like to describe it in such a way that it works 100% according to the description with all absolute paths, so you can be sure that it will work if you do it like this:
- The initial
XAMPP setup is configured in the D directory: \ xampp
If what happened in D: \ xampp \ php \ PEAR \ PhpDocumentor we are not afraid and delete it. There are no smart configurations from xampp.
- Download code
We don’t think about PEAR commands, we download PHPDocumentor directly from the developer's site (links below + my correct version is there)
Unpack everything into the PEAR directory. You will need to perform some magic operations on directories: deleting unnecessary hierarchies, renaming, etc. As a result, the files and the hierarchy, in particular, the phpdoc.bat file should be in this directory: D: \ xampp \ php \ PEAR \ PhpDocumentor
- Configuring the library
Now you need to configure the library itself. To do this, go to the phpdoc.bat file.
In it we will indicate the path to our installed PHP interpreter, as well as switch the working directory.
Instead:
SET phpCli = C: \ usr \ local \ php \ cli \ php.exe
Insert:
SET phpCli = D: \ work \ rumb-software \ xampp \ php \ php.exe
CD / DD: \ xampp \ php \ PEAR \ PhpDocumentor
Attention, a pitfall!
If you will be placing XAMPP on a different drive from C: then when you select the directory (CD command) you need to add the / D argument - it took half an hour, thinking “why doesn’t it see the script?” Until I went to the kitchen to pour tea, accidentally remembering this Microsoft-magic.
- Setting up the IDE
Now we will configure the IDE to work with this extension.
To do this, go to
NetBeans 7.01> Options> PHP> PHPDoc> PhpDoc script.
Insert this line:
D: /xampp/php/PEAR/PhpDocumentor/phpdoc.bat -o HTML: frames: earthli
This line will indicate the IDE executable script and pass additional variables, so by the way they say there you can write something else as parameters. For example, you can learn from the PDF. I didn’t check, and I don’t need it.
Attention pitfall!
Slash should be a straight "/" . If you select through Browse, NetBeans will substitute a backslash.
- Now we’ll set up the path where the documentation will be saved.
Create a project like PHP, well, I won’t describe it here. Let's say I called it example-project and put it in D: / xampp / htdocs / example-project, PHP version 5.3 UTF-8 encoding
Right-click on the project
example-project> properties> PhpDoc> Target Directory
Insert the line (There is also a problem with slashes! ):
D: / xampp / htdocs / phpdoc
- Launch
After these steps, generation is available by right-clicking on the project> Generate PhpDoc.
Even in Include Path, you can connect the directory of the received documentation so that the files are visible through the IDE. In reality, this is generally not necessary, but joy =)
Several problems in the library fixed by me
In the process of generation, I met several problems.
- Notices pop up
. By default, on PHP developer I have the maximum level of errors, warnings, notices and strictures. During the documentation generation, all these errors started to fall into files, basically they created their Smarty class, I express respect for the PHPDocumentor developers - they are doing well. I fixed this problem by forcibly banning it from doing in the library.
Added error_reporting (E_ERROR); in the file
D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc
- Encoding problem
I'm a little Russian and I tend to write Russian comments. Encoding issues have occurred. Here I have for example UTF-8, and in the library the generation templates were sewnother encoding iso-8859-1. The result was nonsense. Knowing how Smarty works, I fixed 3-4 files with code and registered a dynamic variable in the templates. Now the encoding of the output templates can be changed manually in the file D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc using the CHARSET constant, if necessary, the variable {$ charset} can be added to any template from the whole set, I looked at charset headers are not in all templates.
- Help from the public
I’ll add that I consider myself wrong that I didn’t post access to these fixes through the command line, but understand me correctly, I also have no rubber time, I sent the creators a proposal to make my changes to the next revision and it will be easier for them since they are architects of the entire library.
Material Links
PHPDocumentor link to the library:
http://sourceforge.net/projects/phpdocu/files/
Corrected PHPDocumentor: if it does not load, contact the PM. Maybe I put my poor server again.
http://yadi.sk/d/7WnrUy5z0qE7n
Link to documentation on PhpDoc format:
http://manual.phpdoc.org/HTMLframesConverter/default/
Overseas video - setup instructions:
http://netbeans.org/kb/docs /php/screencast-phpdoc.html
The problem with slashes and what error will be in this case is described here:
pachkov.ru/?p=1222
Text for indexing by the search engine:
Error in NetBeans when creating PhpDoc (for Windows)
Error when calling the filter. The following error message was generated:
java.util.regex.PatternSyntaxException: Illegal hexadecimal escape sequence near index 10
(. *) (C: \ xampp \ htdocs \ PhpProject1 \ phpdoc / errors \ .html) (. *)
Thank you for your attention!
UPD: corrected a bunch of stupid sleepy typos
UPD2: I don’t understand who merges karma like rewrites I don’t write, and the article is purely technical and not holistic. It is necessary to remove the anonymity of the change in karma altogether, so that the public can be put on trial. Amazed and offended, but I admit that they began to lessen minus, after the introduction of a 15-point barrier.