1<refentry id="{@id}">
2 <refnamediv>
3  <refname>phpDocumentor tags</refname>
4  <refpurpose>How to use tags in DocBlocks</refpurpose>
5 </refnamediv>
6 <refsynopsisdiv>
7  <refsynopsisdivinfo>
8   <author>
9    Gregory Beaver
10    <authorblurb>Tag Documentation written by {@link mailto:cellog@php.net cellog@php.net}</authorblurb>
11   </author>
12   <copyright>Copyright 2002, Gregory Beaver</copyright>
13  </refsynopsisdivinfo>
14 </refsynopsisdiv>
15 <refsect1 id="{@id manual}">
16  <title>Tags Manual</title>
17  <para>Welcome to the phpDocumentor Tags Manual</para>
18  <para>phpDocumentor tags are very similar to tags for the JavaDoc tool for Sun's Java Programming Language.  Tags are only parsed if they are the first thing on a new line of a DocBlock.  You may use the @ character freely throughout documents as long as it does not begin a new line.  An example:</para>
19  <para>
20   <programlisting role="php">
21   <![CDATA[
22/**
23 * tags demonstration
24 * @author this tag is parsed, but this @version tag is ignored
25 * @version 1.0 this version tag is parsed
26 */
27   ]]>
28   </programlisting>
29  </para>
30  <para>Any tags that phpDocumentor does not recognize will not be parsed, and will be displayed in text flow as if they are part of the DocBlock long description. The example below displays text "tags demonstration @foobar this is silly," and also displays the author as "this tag is parsed, but this @version tag is ignored"
31  </para>
32  <para>
33   <programlisting role="php">
34   <![CDATA[
35/**
36 * tags demonstration
37 * @foobar this is silly
38 * @author this tag is parsed, but this @version tag is ignored
39 */
40   ]]>
41   </programlisting>
42  </para>
43  <para>Inline tags display in the text flow where they appear, and are not separated from the description.  As of version 1.2, there are several inline tags.  The allowed inline tag list is different for tutorials and regular in-code documentation.  See {@tutorial inlinetags.pkg} for more information.
44  </para>
45  <para>The example below will display the text "this function works heavily with <important>foo()</important> to rule the world" where <important>foo()</important> represents a hyperlink that links to the function foo()'s documentation.
46  </para>
47  <para>
48   <programlisting role="php">
49   <![CDATA[
50/**
51 * inline tags demonstration
52 *
53 * this function works heavily with {@}link foo()} to rule the world
54 */
55function bar()
56{
57}
58
59function foo()
60{
61}
62   ]]>
63   </programlisting>
64  </para>
65  <refsect2 id="{@id standard}">
66   <title>Standard phpDocumentor Tags</title>
67   <para>Most tags can be in the DocBlock of any documentable PHP element (for a definition of a documentable PHP element, see {@tutorial elements.pkg}).  Here is a list of the standard tags:
68    <itemizedlist>
69    <listitem><para>{@tutorial tags.access.pkg}</para></listitem>
70    <listitem><para>{@tutorial tags.author.pkg}</para></listitem>
71    <listitem><para>{@tutorial tags.copyright.pkg}</para></listitem>
72    <listitem><para>{@tutorial tags.deprecated.pkg}</para></listitem>
73    <listitem><para>{@tutorial tags.example.pkg}</para></listitem>
74    <listitem><para>{@tutorial tags.ignore.pkg}</para></listitem>
75    <listitem><para>{@tutorial tags.internal.pkg}</para></listitem>
76    <listitem><para>{@tutorial tags.link.pkg}</para></listitem>
77    <listitem><para>{@tutorial tags.see.pkg}</para></listitem>
78    <listitem><para>{@tutorial tags.since.pkg}</para></listitem>
79    <listitem><para>{@tutorial tags.tutorial.pkg}</para></listitem>
80    <listitem><para>{@tutorial tags.version.pkg}</para></listitem>
81    <listitem><para>{@tutorial tags.inlineinternal.pkg}</para></listitem>
82    <listitem><para>{@tutorial tags.inlineinheritdoc.pkg}</para></listitem>
83    <listitem><para>{@tutorial tags.inlinelink.pkg}</para></listitem>
84    </itemizedlist>
85   </para>
86  </refsect2>
87 </refsect1>
88</refentry>