PHP autodocumentation in NetBeans 7.01 using phpDocumentor, telling, configuring, fixing
In this article, you will get new and old knowledge, in particular, some of them appeared quite recently in RuNet, and some of them were introduced by me right on the spot without departing from the cash register.
So you will find out:
On the project I was faced with the need to create normal documentation. Writing separate documentation is not the best way, the basic description of the library can be done in the style of auto-documentation. Began to understand the issue and about the miracle, in NetBeans 7.01, PHPDoc is supported, quite decently and comfortably. 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 under the cat
Some do not know what autodocuments are. Many do not use it because of the size commenting on the code in the old manner in one or two lines, or do not comment at all. This many who sin and I sometimes =). For example, among other meager descriptions, my favorite comment in the title of the 800-hundred line file:
Autodocumentation is amanual for a car such a thing that allows you to write comments on the code. At the same time, inside the IDE, prompts will be displayed on the code, method, function, file, etc. Further, based on it, it is possible to generate complete documentation on the entire code in any HTML, PDF, XML, etc. format. For example, in MSDN , everything you see in the table is created using autodocumentation by the hands of programmers. All the rest is followed 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 have decided to use PHPDocumentor. The work of this library completely satisfies me, especially after my edits in it.
- Code
- IDE hints: we learn that the function does not obviously return a string
- Autodocumentation:
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 proceed to manual configuration. No matter where they write about smart teams like PEAR, it's better to do it like mine. From myself I’ll add that I myself like to describe in such a way that it would work 100% according to the description with all absolute paths, so you can be sure that it will work if done like this:
- Initial setting
XAMPP is configured in the D: \ xampp directory
If that was in D: \ xampp \ php \ PEAR \ PhpDocumentor we are not afraid and delete. There are no smart configurations from xampp.
- Download code
We don’t think about PEAR teams, download PHPDocumentor directly from the developer’s site (links below + my corrected version)
Unpack everything into the PEAR directory. You will need to perform some magic operations on directories: deleting unnecessary hierarchy, renaming, etc. As a result, the files and the hierarchy, in particular, the file phpdoc.bat should appear in this directory: D: \ xampp \ php \ PEAR \ PhpDocumentor
- Library setting
Now you need to configure the library itself. To do this, go to the file phpdoc.bat
In it, we will specify the path to our installed PHP interpreter, as well as make the switching of the working directory.
Instead:
SET phpCli = C: \ usr \ local \ php \ cli \ php.exe
Paste:
SET phpCli = D: \ work \ rumb-software \ xampp \ php \ php.exe
CD / DD: \ xampp \ php \ PEAR \ PhpDocumentor
Attention, underwater stone!
If you place the XAMPP on a different disk from C: then when you select the directory (CD command) you need to add the argument / D - it took half an hour, thinking “what does the script not see?”, Until he went to the kitchen to pour tea, accidentally remembering this Microsoft-magic.
- IDE setup
Now configure the IDE to work with this extension.
To do this, go to
NetBeans 7.01> Options> PHP> PHPDoc> PhpDoc script
Insert this line here:
D: /xampp/php/PEAR/PhpDocumentor/phpdoc.bat -o HTML: frames: earthli
This line will indicate the IDE executable script and pass additional variables, so to the word they say there you can write something else as parameters. For example, you can learn from the result PDF. I did not check, and I do not need it.
Attention underwater!
There must be a straight "/" . If you choose via Browse, then NetBeans will backslash.
- Now set up the path where the documentation will be saved
We create a project like PHP, well, I will not describe it here. Let's say I called it example-project and put it in D: / xampp / htdocs / example-project, PHP version 5.3 encoding UTF-8
Right click on the project
example-project> properties> PhpDoc> Target Directory
We insert a line ( There is a problem with slashes too! ):
D: / xampp / htdocs / phpdoc
- Run
After these actions, generation is available by right-clicking on the project> Generate PhpDoc.
Even in the Include Path, you can connect the directory of the received documentation, so that the files are visible through the IDE. In reality, it is generally not necessary, but joy =)
In the process of generation, I met several problems.
- Pop up notes
I have a default developer level for PHP with the maximum level of errors, warnings, notices and strictures. During the generation of the documentation, all these errors began to fall into the files, mostly creating their Smarty class, expressing respect for the developers of PHPDocumentor - everything is fine with them. I fixed this problem by forcibly forbidding it to do in the library.
Added error_reporting (E_ERROR); in file
D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc
- Problem with the coding
I am a little Russian and I tend to write Russian comments. Encoding problems encountered. Here I have, for example, UTF-8, and in the library another encoding iso-8859-1 was embedded in the generation templates. The result was nonsense. Knowing how Smarty works, I fixed 3-4 files with the code and wrote a dynamic variable into the templates. Now you can change the encoding of output templates manually in the file D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc using the CHARSET constant, if you need to add the variable {{charset} to any template from the entire set, I looked at the charset Headers are not in all templates.
- Public assistance
From myself I’ll add that I consider myself wrong, that I didn’t post access to these fixes via the command line, but do not misunderstand me, I didn’t have a rubber time either, I sent the creators a suggestion to make my edits to the next revision and it would be easier for them they are the architects of the entire library.
PHPDocumentor library link:
http://sourceforge.net/projects/phpdocu/files/
Corrected PHPDocumentor: if it does not load, contact the PM. Perhaps I again put my poor server.
http://yadi.sk/d/7WnrUy5z0qE7n
Link to PhpDoc format documentation:
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 to index the search engine:
NetBeans Error When Creating PhpDoc (for Windows)
Error calling 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) (. *)
Thanks for attention!
UPD: fixed a bunch of stupid sleepy typos
UPD2: I don’t understand who merges karma like rewriting, I don’t write, and the article is purely technical and not holivar. It is generally necessary to remove the anonymity of the change of karma, so that it would be possible to put the public on trial. I was amazed and offended, but I confess that the minus became less after the introduction of a 15-point barrier.
So you will find out:
- Basic information about what autodocument is and how it is done in PHP
- Setting up the phpDocumentor Documentation Generator in NetBeans 7.01
- A link to the phpDocumentor library I corrected with a list of changes I think some might need right away
- Links to read
On the project I was faced with the need to create normal documentation. Writing separate documentation is not the best way, the basic description of the library can be done in the style of auto-documentation. Began to understand the issue and about the miracle, in NetBeans 7.01, PHPDoc is supported, quite decently and comfortably. 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 under the cat
Some do not know what autodocuments are. Many do not use it because of the size commenting on the code in the old manner in one or two lines, or do not comment at all. This many who sin and I sometimes =). For example, among other meager descriptions, my favorite comment in the title of the 800-hundred line file:
// : , . What is autodocumentation in PHP
Autodocumentation 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 have decided to use PHPDocumentor. The work of this library completely satisfies me, especially after my edits in it.
Examples
- Code
/** * * * @param int $arVarOne * @param int $arVarTwo * @return string */ function sum_return_string($arVarOne, $arVarTwo) { $result = $arVarOne + $arVarTwo; return "$result"; // !!! } - IDE hints: we learn that the function does not obviously return a string
- Autodocumentation:
Configuring the autodocumentation script PHPDocumentor
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 proceed to manual configuration. No matter where they write about smart teams like PEAR, it's better to do it like mine. From myself I’ll add that I myself like to describe in such a way that it would work 100% according to the description with all absolute paths, so you can be sure that it will work if done like this:
- Initial setting
XAMPP is configured in the D: \ xampp directory
If that was in D: \ xampp \ php \ PEAR \ PhpDocumentor we are not afraid and delete. There are no smart configurations from xampp.
- Download code
We don’t think about PEAR teams, download PHPDocumentor directly from the developer’s site (links below + my corrected version)
Unpack everything into the PEAR directory. You will need to perform some magic operations on directories: deleting unnecessary hierarchy, renaming, etc. As a result, the files and the hierarchy, in particular, the file phpdoc.bat should appear in this directory: D: \ xampp \ php \ PEAR \ PhpDocumentor
- Library setting
Now you need to configure the library itself. To do this, go to the file phpdoc.bat
In it, we will specify the path to our installed PHP interpreter, as well as make the switching of the working directory.
Instead:
SET phpCli = C: \ usr \ local \ php \ cli \ php.exe
Paste:
SET phpCli = D: \ work \ rumb-software \ xampp \ php \ php.exe
CD / DD: \ xampp \ php \ PEAR \ PhpDocumentor
Attention, underwater stone!
If you place the XAMPP on a different disk from C: then when you select the directory (CD command) you need to add the argument / D - it took half an hour, thinking “what does the script not see?”, Until he went to the kitchen to pour tea, accidentally remembering this Microsoft-magic.
- IDE setup
Now configure the IDE to work with this extension.
To do this, go to
NetBeans 7.01> Options> PHP> PHPDoc> PhpDoc script
Insert this line here:
D: /xampp/php/PEAR/PhpDocumentor/phpdoc.bat -o HTML: frames: earthli
This line will indicate the IDE executable script and pass additional variables, so to the word they say there you can write something else as parameters. For example, you can learn from the result PDF. I did not check, and I do not need it.
Attention underwater!
There must be a straight "/" . If you choose via Browse, then NetBeans will backslash.
- Now set up the path where the documentation will be saved
We create a project like PHP, well, I will not describe it here. Let's say I called it example-project and put it in D: / xampp / htdocs / example-project, PHP version 5.3 encoding UTF-8
Right click on the project
example-project> properties> PhpDoc> Target Directory
We insert a line ( There is a problem with slashes too! ):
D: / xampp / htdocs / phpdoc
- Run
After these actions, generation is available by right-clicking on the project> Generate PhpDoc.
Even in the Include Path, you can connect the directory of the received documentation, so that the files are visible through the IDE. In reality, it is generally not necessary, but joy =)
Some problems in library corrected by me
In the process of generation, I met several problems.
- Pop up notes
I have a default developer level for PHP with the maximum level of errors, warnings, notices and strictures. During the generation of the documentation, all these errors began to fall into the files, mostly creating their Smarty class, expressing respect for the developers of PHPDocumentor - everything is fine with them. I fixed this problem by forcibly forbidding it to do in the library.
Added error_reporting (E_ERROR); in file
D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc
- Problem with the coding
I am a little Russian and I tend to write Russian comments. Encoding problems encountered. Here I have, for example, UTF-8, and in the library another encoding iso-8859-1 was embedded in the generation templates. The result was nonsense. Knowing how Smarty works, I fixed 3-4 files with the code and wrote a dynamic variable into the templates. Now you can change the encoding of output templates manually in the file D: \ xampp \ php \ PEAR \ PhpDocumentor \ phpDocumentor \ phpdoc.inc using the CHARSET constant, if you need to add the variable {{charset} to any template from the entire set, I looked at the charset Headers are not in all templates.
- Public assistance
From myself I’ll add that I consider myself wrong, that I didn’t post access to these fixes via the command line, but do not misunderstand me, I didn’t have a rubber time either, I sent the creators a suggestion to make my edits to the next revision and it would be easier for them they are the architects of the entire library.
Links to materials
PHPDocumentor library link:
http://sourceforge.net/projects/phpdocu/files/
Corrected PHPDocumentor: if it does not load, contact the PM. Perhaps I again put my poor server.
http://yadi.sk/d/7WnrUy5z0qE7n
Link to PhpDoc format documentation:
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 to index the search engine:
NetBeans Error When Creating PhpDoc (for Windows)
Error calling 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) (. *)
Thanks for attention!
UPD: fixed a bunch of stupid sleepy typos
UPD2: I don’t understand who merges karma like rewriting, I don’t write, and the article is purely technical and not holivar. It is generally necessary to remove the anonymity of the change of karma, so that it would be possible to put the public on trial. I was amazed and offended, but I confess that the minus became less after the introduction of a 15-point barrier.
Source: https://habr.com/ru/post/134916/
All Articles