[NetScript CVS] CVS: netscript2/docs/ipdoc HISTORY.txt,NONE,1.1 README.txt,1.1,1.2

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

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

Modified Files:
	README.txt 
Added Files:
	HISTORY.txt 
Log Message:
*added documentation

--- NEW FILE: HISTORY.txt ---
<pre>
/---------------------------------------------------------------------\
| $Id: HISTORY.txt,v 1.1 2002/05/13 11:36:28 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>

Index: README.txt
===================================================================
RCS file: /cvsroot/net-script/netscript2/docs/ipdoc/README.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** README.txt	10 Mar 2002 14:49:44 -0000	1.1
--- README.txt	13 May 2002 11:36:28 -0000	1.2
***************
*** 1,2 ****
--- 1,3 ----
+ <pre>
  /---------------------------------------------------------------------\
  | $Id$
***************
*** 4,8 ****
  | are protected under the terms and conditions of the Artistic License.
  |
! | (C) 2000 - 2001 by Jan Thomä, insOMnia (ko...@in...)
  \---------------------------------------------------------------------/
  
--- 5,9 ----
  | are protected under the terms and conditions of the Artistic License.
  |
! | (C) 2000-2002 by Jan Thomä, insOMnia (ko...@in...)
  \---------------------------------------------------------------------/
  
***************
*** 21,25 ****
  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 ?
--- 22,26 ----
  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 ?
***************
*** 33,38 ****
  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 ?
--- 34,41 ----
  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 ?
***************
*** 41,45 ****
  
  perl ipdoc.pl -f sourceDirectory[,sourceDirectory] [-d destinationDirectory]
!         [-t title]
          
  As sourceDirectory specify the directory where your perl sources are located.
--- 44,48 ----
  
  perl ipdoc.pl -f sourceDirectory[,sourceDirectory] [-d destinationDirectory]
!         [-t title] [-desc <filename|description>]
          
  As sourceDirectory specify the directory where your perl sources are located.
***************
*** 47,51 ****
  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 ?
--- 50,59 ----
  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 ?
***************
*** 55,59 ****
  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:
  
--- 63,68 ----
  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:
  
***************
*** 76,81 ****
                      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)
--- 85,95 ----
                      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)
***************
*** 84,87 ****
--- 98,108 ----
      @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:
***************
*** 103,106 ****
--- 124,136 ----
      }
  
+ 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 ?
  ----------------------------------------------------
***************
*** 108,112 ****
  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 !
--- 138,154 ----
  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 !
***************
*** 120,121 ****
--- 162,164 ----
  
  Jan
+ </pre>