-
Notifications
You must be signed in to change notification settings - Fork 30
/
Copy pathREADME
207 lines (179 loc) · 8.24 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
NAME
PHPDoctor: The PHP Documentation Creator
Peej's Quick & Dirty PHPDoc Clone
VERSION
2.0.5
DESCRIPTION
PHPDoctor is a Javadoc style comment parser for PHP, written with an
emphasis on speed and simplicity. It is designed to be as close a
clone to Javadoc as possible.
REQUIREMENTS
PHP 5.3+ is required. This program may work with older versions of PHP
with the tokenizer extension enabled but it has not been tested and you
are recommended to upgrade to 5.3+ for using this program.
Q&A
Q: WHY DO WE NEED ANOTHER PHPDOC CLONE?
A: I wrote PHPDoctor because I couldn't find a Javadoc clone for PHP
that was small and simple and worked out of the box or that worked
at all. The PHP tokenizer extension has made creating PHPDoc programs
really easy since PHP can now do the hard work for you.
Q: WHY IS PHPDOCTOR DIFFERENT FROM OTHER PHPDOC PROGRAMS?
A: PHPDoctor is very small and easy to use, sticking as closely as
possible to the way Javadoc works, including using the same program
structure and doclet approach to templating. PHPDoctor has a very small
learning curve, most people should be able to generate API
documentation in only a few minutes.
Q: TELL ME MORE ABOUT HOW PHPDOCTOR WORKS
A: PHPDoctor uses the PHP tokenizer extension, this means that it lets
PHP do the parsing of your source code. PHPDoctor just takes the tokens
PHP parses out and turns them into API documentation. This means it will
work for any valid PHP code, no exceptions, it also makes it very fast.
FEATURES
* Fast running speed, uses PHP tokenizer function to take advantage
of PHPs internal parsing functionality.
* Parsing of any valid PHP file, with multiple classes and functions in
the same file.
* Simple output template layer, allowing easy changing of the output
format by copying and editing of a few simple PHP template files.
* Simple to install and use, instant results.
* Will generates API documentation bare bones without Javadoc comments
present.
* Works with both OO and procedural code, also documents global
variables and constants.
* Minimal changes to Sun's Javadoc specification.
* Javadoc extensions compatible with other PHPDoc programs.
* Did I say it was fast?
INSTALLATION
Unzip the archive somewhere, edit the default config file and then run
phpdoc.php with your CLI version of PHP.
FILES
phpdoc.php - PHPDoctor commandline script
default.ini - Default ini file
README - This file
readme.html - HTML version of this file
classes/*.php - Classes used by PHPDoctor
doclets/debug/*.php - Debugging doclet
doclets/standard/*.php - Standard HTML doclet
USAGE
php phpdoc.php <config_file>
To create a config file for your project, copy the default.ini file and
edit it to your needs, it's fully commented.
CONFIGURATION
PHPDoctor supports a number of configuration directives:
* files - Names of files to parse. This can be a single filename, or a
comma separated list of filenames. Wildcards are allowed.
* ignore - Names of files or directories to ignore. This can be a single
filename, or a comma separated list of filenames. Wildcards are NOT
allowed.
* source_path - The directory to look for files in, if not used the
PHPDoctor will look in the current directory (the directory it
is run from).
* subdirs - If you do not want PHPDoctor to look in each sub directory
for files uncomment this line.
* quiet - Quiet mode suppresses all output other than warnings and
errors.
* verbose - Verbose mode outputs additional messages during execution.
* doclet - Select the doclet to use for generating output.
* doclet_path - The directory to find the doclet in. Doclets are
expected to be in a directory named after themselves at the
location given.
* taglet_path - The directory to find taglets in. Taglets allow you to
make PHPDoctor handle new tags and to alter the behavour of
existing tags and their output.
* default_package - If the code you are parsing does not use package
tags or not all elements have package tags, use this setting to
place unbound elements into a particular package.
* overview - Specifies the name of a HTML file containing text for the
overview documentation to be placed on the overview page. The
path is relative to "source_path" unless an absolute path is
given.
* package_comment_dir - Package comments will be looked for in a file
named package.html in the same directory as the first source
file parsed in that package or in the directory given below. If
the directive below is used then package comments should be
named "<packageName>.html".
* globals - Parse out global variables.
* constants - Parse out global constants.
* private - Generate documentation for all class members.
* protected - Generate documentation for public and protected class
members.
* public - Generate documentation for only public class members.
The following directives are specific for the standard doclet:
* d - The directory to place generated documentation in. If the given
path is relative to it will be relative to "source_path".
* windowtitle - Specifies the title to be placed in the HTML <title>
tag.
* doctitle - Specifies the title to be placed near the top of the
overview summary file.
* header - Specifies the header text to be placed at the top of each
output file. The header will be placed to the right of the
upper navigation bar.
* footer - Specifies the footer text to be placed at the bottom of each
output file. The footer will be placed to the right of the
lower navigation bar.
* bottom - Specifies the text to be placed at the bottom of each output
file. The text will be placed at the bottom of the page, below
the lower navigation bar.
* tree - Create a class tree
DOC COMMENTS
A full description of the format of doc comments can be found on the
Sun Javadoc web site (http://java.sun.com/j2se/javadoc/). Doc comments
look like this:
/**
* This is the typical format of a simple documentation comment
* that spans two lines.
*/
TAGS
PHPDoctor supports the following tags:
@abstract
@access access-type
@author name-text
@deprecated deprecated-text
@final
{@link package.class#member label}
{@linkplain package.class#member label}
@package package-name
@param parameter-type parameter-name description
@return return-type description
@see packahge.class#member
@since since-text
@static
@var var-type
@version version-text
Some Javadoc tags are not relevant to PHP and so are ignored, others
are added or slightly changed due to PHPs loose typing:
@abstract is a new tag defining a class or method as abstract.
@access is a new tag and is valid within field and method doc comments.
The first word after the tag should denote the access type of
the field or method.
@final is a new tag defining a class or method as final.
@package is a new tag that places an item into a specific package and
is valid within any doc comment of a top level item.
@param has a parameter-type value added as the first word after the
tag. This value should denote the data type of the parameter.
@return has a return-type value added as the first word after the tag.
This value should denote the methods or functions return data
type.
@static is a new tag defining a class, method or member variable as
static.
PHPDoc 1.1+ also supports the new tags @abstract, @static and @final
which correspond to the equivalent PHP5 keywords and can be used if
required.
COPYRIGHT AND LICENSE
The information below applies to everything in this distribution, except
where noted.
Copyright 2004 by Paul James.
paul@peej.co.uk
http://www.peej.co.uk/
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License along
with this program (COPYING); if not, go to http://www.fsf.org/ or write
to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
MA 02111-1307, USA.