Menu
▾
▴
[NetScript CVS] CVS: netscript2/docs/ipdoc HISTORY.html,NONE,1.1 README.html,NONE,1.1 HISTORY.txt,1.1,NONE README.txt,1.2,NONE
|
From: Jan T. <de...@us...> - 2002-05-13 12:08:09
|
Update of /cvsroot/net-script/netscript2/docs/ipdoc
In directory usw-pr-cvs1:/tmp/cvs-serv16911
Added Files:
HISTORY.html README.html
Removed Files:
HISTORY.txt README.txt
Log Message:
* renamed files to .html to make them readable for windows users
--- NEW FILE: HISTORY.html ---
<pre>
/---------------------------------------------------------------------\
| $Id: HISTORY.html,v 1.1 2002/05/13 11:38:33 derkork Exp $
| IPdoc and all related materials, such as documentation,
| are protected under the terms and conditions of the Artistic License.
|
| (C) 2000-2002 by Jan Thomä, insOMnia (ko...@in...)
\---------------------------------------------------------------------/
IPdoc Version History
-----------------------
Version 1.04 (13.05.2002):
* added index of all documented elements
* added possibility to document package globals
* added @deprecated-tag
* added @callback-tag
* fixed a bug causing weird output if any tag contained
an "@" (e.g. writing your email address to the @author-tag)
Version 1.02 (internal) and 1.03 (16.04.2002):
* layout now tries to imitate javadoc
* added @final-tag
* added possibility to use an HTML-file as package description
Version 1.01 (18.03.2002)
* documentation shows inherited methods for each class
* description of overridden methods is now copied if
no description is provided
* added possibility to document classes
* added a whole bunch of new @-tags
* bugfixes
Version 1.0 (09.03.2002)
* initial release
</pre>
--- NEW FILE: README.html ---
<pre>
/---------------------------------------------------------------------\
| $Id: README.html,v 1.1 2002/05/13 11:38:33 derkork Exp $
| IPdoc and all related materials, such as documentation,
| are protected under the terms and conditions of the Artistic License.
|
| (C) 2000-2002 by Jan Thomä, insOMnia (ko...@in...)
\---------------------------------------------------------------------/
IPdoc Documentation
-------------------
Welcome and thanks for downloading IPdoc the insOMnia perl documenting system.
Small programs should require small documentation, that's what goes for IPdoc.
So here it is:
1. What is IPdoc
----------------
IPdoc is a system for documenting object oriented perl code. It currently
only works for files wich contain classes (and therefore have a pm extension).
It scans all files in a given directory and it's subdirectories for pm-files.
Then it generates a documentation for all these files. It works much like
javadoc for Java does. The documentation is rendered to HTML and can then
be browsed with any browser. Ahh, and did i mention - it's lightning fast!
2. Why IPdoc ? Isn't POD enough ?
---------------------------------
POD has some disadvantages, which I didn't like. First it screws up your code.
While perl is hard to read anyway, putting POD-Stuff into your files makes
it nearly impossible to read. Next is POD doesn't know anything about the
perl language. It's a good formatting tool but you have to take care about
your subs and classes. POD won't do this. Third is, POD is quite outdated. HTML
is much more flexible in design and possibilities. Also HTML is more compatible
than POD (ever tried to read POD under Windows ?). Therefore I decided to
do IPdoc. IPdoc knows about subs and classes and automatically parses your
source for them. Then it generates the HTML code for your classes and subs.
It also generates crosslinks between related classes and subs. You don't need
to document a sub in a subclass, if it is already documented in the superclass.
IpDoc will copy the documentation from the superclass.
3. Kewl! How do i use this thingie ?
-------------------------------------
Easy, really. Just say:
perl ipdoc.pl -f sourceDirectory[,sourceDirectory] [-d destinationDirectory]
[-t title] [-desc <filename|description>]
As sourceDirectory specify the directory where your perl sources are located.
All subdirectories are automatically parsed. As destinationDirectory specify
the directory where the generated HTML should be placed. If none is specified
the current directory will receive the generated HTML. Optionally you can
set a title for your documentation. You can load a description for your
documentation from a file by specifying a filename after the -desc argument.
If your description is quite short, you can specify it directly after the
-desc argument, instead of a filename. IPDoc checks if the argument to the
-desc argument is a valid filename. If it is, the file will be used as
description, if not, the argument itself will become the description.
4. How do I have to format the source ?
---------------------------------------
IPdoc like POD needs some special formatting in the source. However this is
much easier than POD and also looks better so your code isn't screwed up.
IPdoc documentation is done via special formatted comments. An IPdoc
documentation comment looks much like a javadoc documentation comment.
It starts with #/** and ends with #*/. The start and end tags must be on a
separate line.
An example:
#/**
# This is an example documentation comment.
# This sub does this and that....
#*/
sub someSub {
...
}
This is a documentation comment for the sub "someSub". The documentation comment
always documents the sub which follows it. You can add special tags to your
documentation. These tags are:
@param description - a parameter for the sub
@optional description - an optional parameter for the sub
@not-implemented - states that this sub is not yet implemented
@not-standard - states that this sub does not comply to or isn't part of
a standard
@return description - the return value of the sub
@callback - marks this sub as public but only allowed for callback
(e.g SAX-Parser Callbacks)
@public - marks this sub as public useable
@protected - marks this sub as protected (should not be used from outside
but can be overridden by subclasses )
@private - marks this sub as private (should not be used from outside
and should not be overridden by subclasses )
@abstract - marks this implementation as abstract (should be overridden by
subclasses)
@fixme description - states a bug in the sub, yet to be fixed
@note description - adds an implementation note
@author name - sets the author of the sub
@version - sets the version of the sub
@final - states that this sub or class should not be overridden by
subclasses.
@deprecated - states that the sub or class is deprecated and it's use
is no longer encouraged.
Note that you must place each @-tag on a separate line. It may only be
preceded by spaces.
So a complete documentation comment could look like:
#/**
# This sub does ... bla bla bla
# bla bla bla
# ...
# @param the name of your mother
# @return the name of your father
# @public
# @fixme error when you don't have a father
# @note this one is quite senseless
# @version 1.0
# @author Kork of insOMnia
#*/
sub senselessSub {
...
}
As of Version 1.04 you can now document package globals. A package
global is defined by using the "our" keyword of perl. E.g:
#/**
# The current version.
#*/
our $VERSION = "1.04";
4. How is the classname and the inheritance found ?
----------------------------------------------------
The class/package name is determined by the package-statement in your file.
IPdoc looks for a line "package MyPackage::MyClass", which will be used to
extract the packge name. Inheritance is determined by the "use base" -
statement. If you want to add a comment for the whole class (instead of
a comment for a single sub, only) put it before the "package"-statement.
An Example:
#/**
# This is my example class. It is good for...
# @author <a href="mailto:ko...@in...">Jan</a>
#*/
package My::Example::Class;
use base qw(My::Example:SuperClass);
As you can see, you can put HTML into your comments, just like you can do in
Javadoc. Multiple inheritance is not supported at this time.
5. That's quite cool but I miss a feature !
-------------------------------------------
Aye, most possible. I developed this to suit my needs. If you need additional
features please tell me! I'll be glad to add them! Send bugs, features,
comments, questions etc. to ko...@in... .
Now that's it! Go and try it!
Jan
</pre>
--- HISTORY.txt DELETED ---
--- README.txt DELETED ---
|
