PHP на русском: phpDocumentor Manual

PHP5 [/] Для web разработчика Apr 15 phpDocumentor Manual Главная Поиск PHP Smarty Pear Zend phpDoc Mysql Pgsql Контакты phpDocumentor [ class tree: phpDocumentor ] [ index: phpDocumentor ] [ all elements ] README ChangeLog INSTALL FAQ Todo List Packages: phpDocumentor Converters Cpdf HTML_TreeMenu Smarty tests XML_Beautifier Tutorials/Manuals: В пакете: phpDocumentor Guide to Creating Fantastic Documentation phpDocumentor Quickstart Source code for sample1.php Source code for sample2.php Source code for sample3.php phpDocumentor Tutorial Documentable PHP Elements phpDocumentor Tutorials phpDocumentor Manual phpDocumentor tags @abstract @access @author @category @copyright @deprecated @example @final @filesource @global @ignore @internal @license @link @method @name @package @param @property @return @see @since @static @staticvar @subpackage @todo @tutorial @uses @var @version phpDocumentor Inline tags inline {@example} inline {@id} inline {@internal}} inline {@inheritdoc} inline {@link} inline {@source} inline {@toc} inline {@tutorial} Files: actions.php builder.php Classes.inc clone.inc.php clone5.inc.php common.inc.php config.php EventStack.inc HighlightParserTests.php IntermediateParser.inc IntermediateParserTests.php Io.inc new_phpdoc.php ParserClassTests.php ParserDescCleanup.inc ParserPageTests.php phpdoc.inc phpdoc.php phpDocumentorSetupTests.php phpDocumentorTParserTests.php ProceduralPages.inc Publisher.inc Setup.inc.php top.php utilities.php subpackage DescHTML DescHTML.inc subpackage DocBlockTags DocBlockTags.inc subpackage Errors Errors.inc subpackage InlineTags InlineTags.inc subpackage Links LinkClasses.inc subpackage ParserData ParserData.inc subpackage ParserDocBlock ParserDocBlock.inc subpackage ParserElements ParserElements.inc subpackage Parsers Beautifier.php HighlightParser.inc Parser.inc phpDocumentorTParser.inc Tokenizer.php TutorialHighlightParser.inc XMLpackagePageParser.inc subpackage setup find_phpdoc.php subpackage Tutorial PackagePageElements.inc subpackage WordParsers phpDocumentorTWordParser.inc WordParser.inc Classes: Parsers Parser parserDescParser phpDocumentorTParser phpDocumentor_HighlightParser phpDocumentor_HighlightWordParser phpDocumentor_peardoc2_XML_Beautifier phpDocumentor_TutorialHighlightParser phpDocumentor_XML_Beautifier_Tokenizer ppageParser XMLPackagePageParser Classes EventStack Io phpDocumentor_IntermediateParser phpDocumentor_setup ProceduralPages Publisher tests_HighlightParserTests tests_IntermediateParserTests tests_ParserClassTests tests_ParserPageTests tests_phpDocumentorSetupTests tests_phpDocumentorTParserTests DescHTML parserB parserBr parserCode parserDescVar parserI parserKbd parserList parserPre parserSamp DocBlockTags parserAccessTag parserExampleTag parserFileSourceTag parserLicenseTag parserLinkTag parserMethodTag parserNameTag parserParamTag parserPropertyReadTag parserPropertyTag parserPropertyWriteTag parserReturnTag parserSeeTag parserStaticvarTag parserTag parserTutorialTag parserUsedByTag parserUsesTag parserVarTag Errors ErrorTracker RecordError RecordWarning InlineTags parserExampleInlineTag parserIdInlineTag parserInheritdocInlineTag parserInlineTag parserLinkInlineTag parserSourceInlineTag parserTocInlineTag parserTutorialInlineTag Links abstractLink classLink constLink defineLink functionLink globalLink methodLink pageLink tutorialLink varLink Tutorial parserCData parserEntity parserXMLDocBookTag ParserData parserBase parserData parserPage parserStringWithInlineTags WordParsers ObjectWordParser phpDocumentorTWordParser WordParser ParserDocBlock parserDesc parserDocBlock ParserElements parserClass parserConst parserDefine parserElement parserFunction parserGlobal parserInclude parserMethod parserPackagePage parserTutorial parserVar phpDocumentor Guide to Creating Fantastic Documentation What makes good documentation? This is unanswerable, but there are a few things to keep in mind Gregory Beaver cellog@php.net Why write good documentation for open source code? Writing good documentation is essential to the success of any software project. The quality of documentation can be even more important than the quality of the code itself, as a good first impression will prompt developers to look further into your code. phpDocumentor is designed to make it easier to create documentation. phpDocumentor even makes it possible to generate separate sets of documentation from the same source! Writing Great Documentation Consider the audience The first question any writer must ask is "Who is my audience?" This will answer many questions. For most software, such as any MS product, the software is intended only to be used. The programmers are the only people who have access to the source code. The challenge in this case is to write good documentation for end-users. When writing documentation for an open-source project intending to be both used and extended, this challenge is magnified by the fact that many people will also intend to extend the source, or even find obscure bugs and fix them. These two audiences tend to be opposed to each other in their needs. An end-user generally wants: Instruction-style writing, that explains and describes general concepts more than how a particular variable is used Interface information only, no low-level details Examples of how to use, and tutorials Whereas a programmer may want in addition: Details on how program elements interact, which elements use others Where in the source code an action or series of actions occurs How to extend the code to add new functionality These two kinds of users can not be serviced by just API documentation or just tutorials, but a subtle blend of the two. Using phpDocumentor to make documentation for two separate audiences In essence, there may need to be two separate sets of documentation! phpDocumentor can be used to create this option using a few things. First, using the command-line file-selection options, one can write two sets of documentation, one for end-users, and the other for programmers, and put them in different subdirectories. For instance, one could put enduser docs in "enduser/tutorials" and programmer docs in "programmer/tutorials." In addition, using the @access tag, one can mark programmer-level elements with @access private, and they will be ignored by default. The @internal tag and inline {@internal}} inline tag construct can be used to mark documentation that is low-level or internal to a smaller audience of developers. When creating programmer documentation, turn on the parse private option (see -pp, --parseprivate ), and the low-level detail will be generated. More important, the in-code documents in your DocBlocks must be written for both end-users and programmers wherever possible. phpDocumentor uses the chaining feature of tutorials to link together related documentation like chapters in a book, and this is another way to organize documentation. Experiment, and find what's best for your project's needs. Tips on Revising There are many ways of creating good documentation, but perhaps the best is to read what you have written from different perspectives. Open up your documentation, and try to use it to figure out your software project. If this is difficult, go back and edit or rewrite. Remove anything that is confusing or unnecessary, make sure everything is there that is needed, and then when it seems good, ask a php user that doesn't know your project, or even a non-programmer to read it and use their reactions to tailor the documentation. Conclusion The use of phpDocumentor will definitely improve the look and feel of your documentation, but don't stop there, let it help you to create truly dynamic documents that are easily maintained and kept up-to-date. After all, great docs for great programs will help to secure PHP's rightful throne as the best out there! References for learning how to use phpDocumentor phpDocumentor Quickstart Поддержать сайт на родительском проекте КГБ Фрейм с коментариями ©2014 КГБ: Киевская городская библиотека . All Rights Reserved - Справочники php5.kiev.ua . Киев , Украина . Ua-IX . GEO: 50,433334 30,516666 Webmaster email | Рекламная служба +38 050 4468872 9:00 - 21:00 | Обмен ссылками