[NetScript CVS] CVS: netscript2/docs/ipdoc README.txt,NONE,1.1 wipeout.project,NONE,1.1

[Jan T. <de...@us...>]

Update of /cvsroot/net-script/netscript2/docs/ipdoc
In directory usw-pr-cvs1:/tmp/cvs-serv4995

Added Files:
	README.txt wipeout.project 
Log Message:
* added documentation for IPdoc

--- NEW FILE: README.txt ---
/---------------------------------------------------------------------\
| $Id: README.txt,v 1.1 2002/03/10 14:49:44 derkork Exp $
| IPdoc and all related materials, such as documentation,
| are protected under the terms and conditions of the Artistic License.
|
| (C) 2000 - 2001 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.

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 code for your classes and subs. It also 
generates crosslinks between related classes. 

3. Kewl! How do i use this thingie ?
-------------------------------------
Easy, really. Just say:

perl ipdoc.pl -f sourceDirectory[,sourceDirectory] [-d destinationDirectory]
        [-t title]
        
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.

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 #*/. Then end tag 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
    @public - marks this sub as public useable
    @private - marks this sub as private (should not be used from outside)                    
    @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

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 {
    ...
    }

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.

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

--- NEW FILE: wipeout.project ---
b
C DmDictionary 0 9d70 8 
c 0 9db5 9 
C Category 1 1d9a 
c 0 9de9 4 
C DmString 2 9df0 2 e3 
c 2 9def a defaultExe 
C DmSet 3 9df2 1 
c 2 1da9 2 e3 
L 1da9 
c 2 9df1 b executables 
c 3 9ded 3 
c 2 1db0 3 *.C 
L 1db0 
c 2 1db3 4 *.cc 
L 1db3 
c 2 1db6 5 *.cpp 
L 1db6 
c 2 9dec a extensions 
c 2 9deb a CPP_source 
c 2 9dea 4 name 
c 2 9db7 a CPP_source 
c 1 1dcb 
c 0 9e2f 4 
c 2 9e36 2 e3 
c 2 9e35 a defaultExe 
c 3 9e38 1 
c 2 1dd8 2 e3 
L 1dd8 
c 2 9e37 b executables 
c 3 9e33 1 
c 2 1ddf 3 *.c 
L 1ddf 
c 2 9e32 a extensions 
c 2 9e31 8 C_source 
c 2 9e30 4 name 
c 2 9db8 8 C_source 
c 1 1df4 
c 0 9e69 4 
c 2 9e70 2 e3 
c 2 9e6f a defaultExe 
c 3 9e72 1 
c 2 1e01 2 e3 
L 1e01 
c 2 9e71 b executables 
c 3 9e6d 1 
c 2 1e08 3 *.e 
L 1e08 
c 2 9e6c a extensions 
c 2 9e6b 6 Eiffel 
c 2 9e6a 4 name 
c 2 9db9 6 Eiffel 
c 1 1e1d 
c 0 9ea3 4 
c 2 9eaa 2 e3 
c 2 9ea9 a defaultExe 
c 3 9eac 1 
c 2 1e2a 2 e3 
L 1e2a 
c 2 9eab b executables 
c 3 9ea7 4 
c 2 1e31 3 *.F 
L 1e31 
c 2 1e34 3 *.f 
L 1e34 
c 2 1e37 5 *.for 
L 1e37 
c 2 1e3a 5 *.fpp 
L 1e3a 
c 2 9ea6 a extensions 
c 2 9ea5 7 Fortran 
c 2 9ea4 4 name 
c 2 9dba 7 Fortran 
c 1 1e4f 
c 0 9ee9 4 
c 2 9ef0 2 e3 
c 2 9eef a defaultExe 
c 3 9ef2 1 
c 2 1e5c 2 e3 
L 1e5c 
c 2 9ef1 b executables 
c 3 9eed 2 
c 2 1e63 3 *.H 
L 1e63 
c 2 1e66 3 *.h 
L 1e66 
c 2 9eec a extensions 
c 2 9eeb 6 Header 
c 2 9eea 4 name 
c 2 9dbb 6 Header 
c 1 1e7b 
c 0 9f27 4 
c 2 9f2e 9 surfboard 
c 2 9f2d a defaultExe 
c 3 9f30 2 
c 2 1e88 2 e3 
L 1e88 
c 2 1e8b 9 surfboard 
L 1e8b 
c 2 9f2f b executables 
c 3 9f2b 2 
c 2 1e92 5 *.htm 
L 1e92 
c 2 1e95 6 *.html 
L 1e95 
c 2 9f2a a extensions 
c 2 9f29 4 Html 
c 2 9f28 4 name 
c 2 9dbc 4 Html 
c 1 1eaa 
c 0 9f69 4 
c 2 9f70 2 e3 
c 2 9f6f a defaultExe 
c 3 9f72 1 
c 2 1eb7 2 e3 
L 1eb7 
c 2 9f71 b executables 
c 3 9f6d 1 
c 2 1ebe 6 *.java 
L 1ebe 
c 2 9f6c a extensions 
c 2 9f6b 4 Java 
c 2 9f6a 4 name 
c 2 9dbd 4 Java 
c 1 1ed3 
c 0 9fa3 4 
c 2 9faa 2 e3 
c 2 9fa9 a defaultExe 
c 3 9fac 1 
c 2 1ee0 2 e3 
L 1ee0 
c 2 9fab b executables 
c 3 9fa7 1 
c 2 1ee7 5 *.tex 
L 1ee7 
c 2 9fa6 a extensions 
c 2 9fa5 5 Latex 
c 2 9fa4 4 name 
c 2 9dbe 5 Latex 
c 1 1efc 
c 0 9fdd 4 
c 2 9fe4 2 e3 
c 2 9fe3 a defaultExe 
c 3 9fe6 1 
c 2 1f09 2 e3 
L 1f09 
c 2 9fe5 b executables 
c 3 9fe1 0 
c 2 9fe0 a extensions 
c 2 9fdf 5 Other 
c 2 9fde 4 name 
c 2 9dbf 5 Other 
c 2 9db4 a categories 
c 0 9dc1 1 
C ProjectDir 4 1f26 
c 2 1f27 16 netscript2/docs/ipdoc/ 11 81 
c 2 1f28 0  0 
c 2 9dc3 16 netscript2/docs/ipdoc/ 
c 2 9dc0 b directories 
C DmBag 5 9d7c 1 
c 2 9db2 d2 b
C DmDictionary 0 9d7e 3 
C DmString 1 9d90 36 b
C DmSet 0 9bf3 1 
C DmString 1 9d65 5 Other 
L 9d65  
c 1 9d8f a categories 
c 1 9d80 a README.txt 
c 1 9d7f 4 name 
C DmInteger 2 9d92 1 
c 1 9d91 9 substMode  
c 2 9db3 5 files 
c 2 9d78 94 xterm -ls -fn -*-lucidatypewriter-medium-r-normal-*-12-* -bg gray90 -T Program -geometry 80x10+0+0 -e "[set command with 'Project->Launch Command']" 
c 2 9d77 6 launch 
c 2 9d74 4 make 
c 2 9d73 4 make 
c 2 9d76 0  
c 2 9d75 8 makeFile 
c 5 9d79 0 
c 2 9d7b 7 modules 
c 2 9d72 5 ipdoc 
c 2 9d71 4 name