WIKIBOOKS
DISPONIBILI
?????????

ART
- Great Painters
BUSINESS&LAW
- Accounting
- Fundamentals of Law
- Marketing
- Shorthand
CARS
- Concept Cars
GAMES&SPORT
- Videogames
- The World of Sports

COMPUTER TECHNOLOGY
- Blogs
- Free Software
- Google
- My Computer

- PHP Language and Applications
- Wikipedia
- Windows Vista

EDUCATION
- Education
LITERATURE
- Masterpieces of English Literature
LINGUISTICS
- American English

- English Dictionaries
- The English Language

MEDICINE
- Medical Emergencies
- The Theory of Memory
MUSIC&DANCE
- The Beatles
- Dances
- Microphones
- Musical Notation
- Music Instruments
SCIENCE
- Batteries
- Nanotechnology
LIFESTYLE
- Cosmetics
- Diets
- Vegetarianism and Veganism
TRADITIONS
- Christmas Traditions
NATURE
- Animals

- Fruits And Vegetables



ARTICLES IN THE BOOK

  1. Accrisoft
  2. Active calendar
  3. ActiveState Komodo
  4. AdLogger
  5. Apache HTTP Server
  6. AutoContent
  7. BakeSale
  8. Bblocked
  9. BBlog
  10. BbPress
  11. Beehive Forum
  12. B2evolution
  13. Bluefish
  14. Chlorine Boards
  15. CMScout
  16. CMSimple
  17. CMS Made Simple
  18. Content Protector
  19. Coppermine Photo Gallery
  20. CRE Loaded
  21. Cutenews
  22. DB DataObject FormBuilder
  23. Divine
  24. Dokeos
  25. DotOrg
  26. Dragonfly CMS
  27. Dreamweaver
  28. Drupal
  29. Dynamic Web page
  30. E107
  31. Eclipse
  32. 25 Essential PHP Functions
  33. FusionBB
  34. Gallery Project
  35. Gedit
  36. Group-Office
  37. HawHaw
  38. IceBB
  39. 4images
  40. Introduction to PHP
  41. Introduction to PHP Learning Guide
  42. IonCube Ltd.
  43. JEdit
  44. Joomla
  45. LAMP
  46. Linux
  47. List of PHP editors
  48. List of PHP libraries
  49. Maguma
  50. Mambo
  51. MediaWiki
  52. MetaBB
  53. Midgard
  54. MiniBB
  55. Monkey Boards
  56. Moodle
  57. MySQL
  58. Ning
  59. Nucleus CMS
  60. Nuke-Evolution
  61. NuSphere Corporation
  62. OpenPHPNuke
  63. Orbit42-Base
  64. OsCommerce
  65. Paamayim Nekudotayim
  66. Phalanger
  67. Php
  68. PHP accelerator
  69. PhpBB
  70. PhpBB Reloaded
  71. PHP Constants
  72. PHPDoc
  73. PhpDocumentor
  74. PHPEdit
  75. PHP Excel Reader
  76. PHP Extension Community Library
  77. PhpGedView
  78. PHP-GTK
  79. PhpLDAPadmin
  80. PHP License
  81. Phplist
  82. PhpMyAdmin
  83. PhpMyVisites
  84. Phpns
  85. PHP-Nuke
  86. PhpPgAdmin
  87. PhpWiki
  88. PmWiki
  89. PostNuke
  90. PSPad
  91. PunBB
  92. PuzzleApps
  93. Quanta Plus
  94. Rasmus Lerdorf
  95. ReallySimpleCMS
  96. Refbase
  97. RGameScript Pro
  98. Santy
  99. SciTE
  100. Serendipity weblog
  101. Simple Machines Forum
  102. SimpleXML
  103. SiteFrame
  104. Smarty
  105. SquirrelMail
  106. Textpattern
  107. Thatware
  108. Think Tank Forums
  109. TikiWiki
  110. TorrentVolve
  111. TYPO3
  112. UBB.threads
  113. UltraEdit
  114. UNITED-NUKE
  115. Variables in PHP
  116. VBulletin
  117. WakkaWiki
  118. Web Application Structure for PHP
  119. Webwm
  120. Wikindx
  121. WikkaWiki
  122. WordPress
  123. WordPress MU
  124. Xaraya
  125. XOOPS
  126. Zen Cart
  127. Zend Engine
  128. Zend Studio
  129. Zend Technologies
  130. Zentri
  131. ZPanel

 



PHP LANGUAGE AND PRODUCTS
This article is from:
http://en.wikipedia.org/wiki/PHPDoc

All text is available under the terms of the GNU Free Documentation License: http://en.wikipedia.org/wiki/Wikipedia:Text_of_the_GNU_Free_Documentation_License 

PHPDoc

From Wikipedia, the free encyclopedia

 

PHPDoc is an adoption of Javadoc to the PHP world. It is a formal standard for commenting PHP code. It offers three main advantages to generic or random commenting styles: First, it makes comments readable in a standard method encouraging programmers to define and comment on aspects of the code that normally would be ignored. Second, it allows external document generators like PHPDocumentor to create well formated and easy to understand documentation of the API. Third, it allows some IDEs such as Zend Studio to interpret variable types and other ambiguities in the loosely typed language.

PHPDoc supports documentation of both object-oriented and procedural code.

Components of PHPDoc

DocBlock

A DocBlock is an extended C++-style PHP comment that begins with "/**" and has an "*" at the beginning of every line. DocBlocks precede the element they are documenting.

Any line within a DocBlock that doesn't begin with a * will be ignored. To document function "foo()", place the DocBlock immediately before the function declaration:

/** * This is a DocBlock comment */function foo(){}

This example will apply the DocBlock to "define('me',2);" instead of to "function foo()":

/** * DocBlock for function foo? * * No, this will be for the constant me! */define('me',2);function foo($param = me){}

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented, see Elements of the source code that can be documented

A DocBlock contains three basic segments in this order:

  • Short Description
  • Long Description
  • Tags

The Short Description starts on the first line, and can be terminated with a blank line or a period. A period inside a word (like example.com or 0.1 %) is ignored. If the Short Description would become more than three lines long, only the first line is taken. The Long Description continues for as many lines as desired and may contain html markup for display formatting. Here is a sample DocBlock with a Short and a Long Description:

/** * return the date of Easter *  * Using the formula from "Formulas that are way too complicated for anyone to * ever understand except for me" by Irwin Nerdy, this function calculates the * date of Easter given a date in the Ancient Mayan Calendar, if you can also * guess the birthday of the author. */

Optionally, you may enclose all paragraphs in a <p></p> tag. Be careful, if the first paragraph does not begin with <p>, phpDocumentor will assume that the DocBlock is using the simple double linebreak to define paragraph breaks as in:

/** * Short desc * * Long description first sentence starts here * and continues on this line for a while * finally concluding here at the end of * this paragraph * * The blank line above denotes a paragraph break */

Here is an example of using <p>

/** * Short desc * * <p>Long description first sentence starts here * and continues on this line for a while * finally concluding here at the end of * this paragraph</p> * This text is completely ignored! it is not enclosed in p tags * <p>This is a new paragraph</p> */

phpDocumentor also supports JavaDoc's DocBlock format through the command-line option -j, --javadocdesc. Due to the non-xhtml compliant unmatched p tag, we highly recommend you avoid this syntax whenever possible

/** * <p> * Short desc is only to the first period. * This means a sentence like: * "Parses Mr./Mrs. out of $_GET." will * parse a short description of "Parses Mr." * which is rather silly.  Long description is * the entire DocBlock description including the * Short desc, and paragraphs begin where p is like: * <p> * The p above denotes a paragraph break */

phpDocumentor will convert all whitespace into a single space in the long description, use paragraph breaks to define newlines, or <pre>, as discussed in the next section.

DocBlock Description Details

In some parsers the long and short description of a DocBlock is parsed for a few select html tags that determine additional formatting. Because not all HTML is allowed, they will generally be converted into plain text or more content specific tags. For example, a <b> tag may be converted into <emphasis> in DocBook.

Here is a list of tags supported by PHPDocumentor:

  • <b> -- emphasize/bold text
  • <code> -- Use this to surround php code, some converters will highlight it
  • <br> -- hard line break, may be ignored by some converters
  • <i> -- italicize/mark as important
  • <kbd> -- denote keyboard input/screen display
  • <li> -- list item
  • <ol> -- ordered list
  • <p> -- If used to enclose all paragraphs, otherwise it will be considered text
  • <pre> -- Preserve line breaks and spacing, and assume all tags are text (like XML's CDATA)
  • <samp> -- denote sample or examples (non-php)
  • <ul> -- unordered list
  • <var> -- denote a variable name

For the rare case when the text "<b>" is needed in a DocBlock, use a double delimiter as in <<b>>. phpDocumentor will automatically translate that to the physical text "<b>".

Using <code> and <pre>

Both <code> and <pre> ignore any html listed above except for their closing tags </code> for <code> and </pre> for <pre>

DocBlock Templates

The purpose of a DocBlock template is to reduce redundant typing. For instance, if a large number of class variables are private, one would use a DocBlock template to mark them as private. DocBlock templates simply augment any normal DocBlocks found in the template block.

A DocBlock template is distinguished from a normal DocBlock by its header. Here is the most basic DocBlock template:

/**#@+ * */

The text that marks this as a DocBlock template is "/**#@+" - all 6 characters must be present. DocBlock templates are applied to all documentable elements until the ending template marker:

/**#@-*/

Note that all 8 characters must appear as "/**#@-*/" in order for phpDocumentor to recognize them as a template.

Page Level DocBlocks

A page-level DocBlock is the only DocBlock that cannot precede the element that it is documenting, as there is no way to precede a file. To solve this issue, the way phpDocumentor finds a page-level DocBlock is to parse the first DocBlock in a file as the page-level DocBlock, with certain conditions.

<?php/** * Page-level DocBlock */define('oops','Page-level DocBlock it is not!');?>

This last example has one DocBlock, and it is the first DocBlock in a file, but it is not a Page-level DocBlock. How can phpDocumentor tell the difference between a Page-level DocBlock and any other DocBlock? Simple:

<?php/** * Pretend this is a file * * Page-level DocBlock is here because it is the first DocBlock * in the file, and contains a @package tag * @package pagepackage */ define("almost","Now the Page-level DocBlock is for the page, and the  Define has no docblock");?>

In phpDocumentor version 1.2.2, a Page-level DocBlock is the first DocBlock in a file if it contains a @package tag. However, this example will raise a warning like WARNING in test.php on line 8: Page-level DocBlock precedes "define almost", use another DocBlock to document the source element. You can eliminate the warning by adding documentation to the define as follows:

<?php/** * Page-level DocBlock * @package pagepackage *//** * Define DocBlock */define("ahhhh","Now the Page-level DocBlock is for the page, and the Define DocBlock for the define");?>

Now, the page has its documentation, and the define has its own documentation.

So, a DocBlock is a page-level DocBlock IF AND ONLY IF it is both:

  1. The first DocBlock in a file
  2. One of:
  3. Contains a @package tag
  4. Immediately followed by another DocBlock for any documentable PHP element this is deprecated, always use a @package tag

A Page-level DocBlock may have any of the standard phpDocumentor Tags (see Standard phpDocumentor Tags) plus the following tags:

  • @package
  • @subpackage

phpDocumentor will not document a file like the first example, there must be at least one documentable PHP element in the file.

Tags

Tags are single words prefixed by a "@" symbol. Tags inform parsers how to present information and modify display of documentation as well as allow the IDE to define variable types. All tags are optional, but if you use a tag, they do have specific requirements to parse properly.

Some tags are provided in the following table.

 

In addition, some parsers allow two addition inline tags: {@id}, used to allow direct linking to sections in a tutorial, and {@toc}, used to generate a table of contents from {@id}s in the file. Think of {@id} like an <a name="idname"*gt; HTML tag as it serves the same function.

For more in depth discussion of PHPDoc tags, see http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html

Packages

To understand the role of packages and how to use @package, it is important to know the logic behind packaging in PHP. The quest for structured programming led to the invention of functions, then classes, and finally packages. Traditionally, a re-usable software module was a collection of variables, constants and functions that could be used by another software package. PHP is an example of this model, as there are many extensions that consist of constants and functions like the tokenizer extension. One can think of the tokenizer extension as a package: it is a complete set of data, variables and functions that can be used in other programs. A more structured format of this model is of course objects, or classes. A class contains variables and functions (but no constants in PHP). A single class packages together related functions and variables to be re-used.

phpDocumentor defines package in two ways:

  • Functions, Constants and Global Variables are grouped into files (by the filesystem), which are in turn grouped into packages using the @package tag in a page-level DocBlock
  • Methods and Class Variables are grouped into classes (by PHP), which are in turn grouped into packages in a Class DocBlock

These two definitions of package are exclusive. In other words, it is possible to have classes of a different package of the file that contains it! Here's an example:

See also

  • PHPDocumentor
  • List of documentation generators
  • Comparison of documentation generators

External links

  • PHP Doc Home
  • PHP Home Page
Retrieved from "http://en.wikipedia.org/wiki/PHPDoc"