{"id":1450,"date":"2018-01-19T19:22:51","date_gmt":"2018-01-19T19:22:51","guid":{"rendered":"http:\/\/goofy-trucks.flywheelsites.com\/how-to-document-your-php-classes-page-3\/"},"modified":"2018-01-19T19:24:48","modified_gmt":"2018-01-19T19:24:48","slug":"how-to-document-your-php-classes-page-3","status":"publish","type":"post","link":"https:\/\/phpbuilder.com\/how-to-document-your-php-classes-page-3\/","title":{"rendered":"How To Document Your PHP Classes Page 3"},"content":{"rendered":"
\n
\n
By Stefano Locati<\/div>\n
on August 25, 2000<\/div>\n<\/p><\/div>\n
\n
\nI decided to test this script on its own PHP source and I found it working partially: it could just generate the
\ndocumentation of the classes (neatly formatted), but not the summaries. I don’t know if this happens just on my
\nmachine, but it just stopped with a core dump (PHP 4.0 pl2 on a RedHat 6.2) when trying to generate the summaries.
\nSupposing you’ve a PHP executable installed in \/usr\/local\/bin the syntax for calling it is (to have some results
\nI had to give full paths of both the php files and the output directory) <\/div>\n
\n
\n.\/phpautodoc <php_files> -o <output_dir>\n<\/pre>\n<\/div>\n
\nphpdoc<\/a> is a tool to maintain documentation about PHP files
\non the web and it is best suited for distributed development efforts. The documentation gets written into a
\nMySQL database; after installing it you can document your classes by adding them using a web interface. This
\nis really interesting but is a way to maintain a low level documentation separatated from source code which
\nas I said it’s not very convenient.<\/div>\n
A General Purpose Tool<\/h2>\n
\nAfter experiencing some frustration trying all these tools without much success and until a standard solution is
\nproposed by the Pear Project<\/a>, I found a working tool completely
\nunrelated to PHP in the Open Source Projects at Apple<\/a> website. The
\nname of the project is HeaderDoc<\/a>. As the website
\nstates HeaderDoc is a tool for generating HTML reference documentation for comments of C or C++ header files.
\nIt is written in Perl for easy portability. Similar to JavaDoc, it allows developers to easily document their
\ninterfaces and export that information into HTML.<\/i><\/div>\n
\nYes, you’ve read well, HeaderDoc supports just C and C++. No other languages, but it happens that, unlike
\nJavadoc, it relies mostly on tags written inside comments and so can works well for PHP too with minor
\nmodifications (I will explain later). The tags are Javadoc-like, some examples of Headerdoc tags are
\n@class, @function and @var.<\/div>\n
Documenting A Class<\/h2>\n
\nOk so let’s dive into details now. First let’s take a look to how a class can be documented.<\/div>\n
\n
\n\/*! @class BagItem\n    @abstract An item in the shopping bag - it is a shopitem with quantity\n    @discussion A BagItem object may be constructed without previous instantiation \n\tof neither ShopItem nor Product\n*\/\n<\/pre>\n<\/div>\n
\n\"Documentation<\/div>\n
\nDocumentation of a class. On the left frame it is possible to choose a method of the class.<\/i><\/div>\n
\nThe first thing to notice is that the style used to open comments is not exactly like Javadoc comments
\n\/**<\/code> (a slash and two asterisks), but is instead \/*!<\/code> (a slash, an asterisk
\nand an exclamation mark). Tags are different too, but they work in a similar way.
\nFor example the first tag is the @class<\/code> tag which is used to document a class,
\nthis tag is followed by the class name. The next tag is the @abstract<\/code> tag which is
\nan optional tag describing in a few words the meaning of the class, while the @discussion<\/code>
\ntag is another optional tag used for a more in depth discussion. Of course it’s up
\nto you to decide wether to write everything in the @discussion<\/code> tag or use the
\n @abstract<\/code> too, but remember that in general, the more specific tags
\n  you use, the better the results are.<\/div>\n<\/div>\n
<\/p>\n
\n
\u00ab Previous Page<\/a><\/div>\n
1<\/a> <\/div>\n
| <\/div>\n
2<\/a> <\/div>\n
| <\/div>\n
3<\/div>\n
| <\/div>\n
4<\/a> <\/div>\n
| <\/div>\n
5<\/a> <\/div>\n
Next Page \u00bb<\/a><\/div>\n<\/div><\/div>\n","protected":false},"excerpt":{"rendered":"
By Stefano Locati on August 25, 2000 I decided to test this script on its own PHP source and I found it working partially: it could just generate the documentation of the classes (neatly formatted), but not the summaries. I don’t know if this happens just on my machine, but… <\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[3],"tags":[],"class_list":["post-1450","post","type-post","status-publish","format-standard","hentry","category-tutorials"],"_links":{"self":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts\/1450","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/comments?post=1450"}],"version-history":[{"count":1,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts\/1450\/revisions"}],"predecessor-version":[{"id":2238,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/posts\/1450\/revisions\/2238"}],"wp:attachment":[{"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/media?parent=1450"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/categories?post=1450"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/phpbuilder.com\/wp-json\/wp\/v2\/tags?post=1450"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}