uk.ac.starlink.ttools.build
Class XmlDoclet

java.lang.Object
  extended by uk.ac.starlink.ttools.build.MemberDoclet
      extended by uk.ac.starlink.ttools.build.XmlDoclet
Direct Known Subclasses:
FullXmlDoclet

public abstract class XmlDoclet
extends MemberDoclet

Doclet which documents public static members of classes in SUN-type XML. This abstract superclass provides basic XML-type doclet functionality.

Optional doclet flags beyond the standard ones are:

-o file
Specify output file

Since:
6 Sep 2004
Author:
Mark Taylor (Starlink)

Constructor Summary
protected XmlDoclet(RootDoc root)
           
 
Method Summary
static String doctorText(String text)
          Attempts to turn HTML text into XML.
protected  void endClass()
          End output of documentation for the most recently started class.
protected  void endMember()
          End output of the most recently started member.
 void flush()
           
static int optionLength(String option)
          Define permitted command-line flags.
 void out(String line)
          Outputs a single line of output to the current output stream.
 void out(String[] lines)
          Outputs some lines of text to the current output stream.
protected  void outDescription(String descrip)
          Output a description item.
protected  void outExamples(String[] examples)
          Output examples of the current documentandum (presumably a method).
protected  void outItem(String name, String val)
          Output an item to the current documentandum (class/member).
protected  void outParameters(Parameter[] param, String[] comments)
          Output parameters to the current documentandum (presumably a method).
protected  void outReturn(Type rtype, String rdesc)
          Output return value for the current method.
protected  void startClass(ClassDoc clazz)
          Begin output of documentation for a given class.
protected  void startMember(MemberDoc mem, String memType, String memName)
          Begin output of documentation for a given clas member (field or method).
 
Methods inherited from class uk.ac.starlink.ttools.build.MemberDoclet
process, processClass, processPackage, pWrap, typeString, warning
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XmlDoclet

protected XmlDoclet(RootDoc root)
             throws IOException
Throws:
IOException
Method Detail

optionLength

public static int optionLength(String option)
Define permitted command-line flags. This method is part of the Doclet public interface.


startClass

protected void startClass(ClassDoc clazz)
                   throws IOException
Description copied from class: MemberDoclet
Begin output of documentation for a given class. Subsequent calls to outItem refer to this.

Specified by:
startClass in class MemberDoclet
Parameters:
clazz - class to document
Throws:
IOException

endClass

protected void endClass()
                 throws IOException
Description copied from class: MemberDoclet
End output of documentation for the most recently started class.

Specified by:
endClass in class MemberDoclet
Throws:
IOException

startMember

protected void startMember(MemberDoc mem,
                           String memType,
                           String memName)
                    throws IOException
Description copied from class: MemberDoclet
Begin output of documentation for a given clas member (field or method). Subsequent calls to outItem etc refer to this.

Specified by:
startMember in class MemberDoclet
Parameters:
mem - class member
memType - some user-viewable (that is not necessarily using technical terms) description of what kind of member it is
memName - some user-viewable label for the member
Throws:
IOException

endMember

protected void endMember()
                  throws IOException
Description copied from class: MemberDoclet
End output of the most recently started member.

Specified by:
endMember in class MemberDoclet
Throws:
IOException

outDescription

protected void outDescription(String descrip)
                       throws IOException
Description copied from class: MemberDoclet
Output a description item.

Specified by:
outDescription in class MemberDoclet
Parameters:
descrip - description string
Throws:
IOException

outItem

protected void outItem(String name,
                       String val)
Description copied from class: MemberDoclet
Output an item to the current documentandum (class/member).

Specified by:
outItem in class MemberDoclet
Parameters:
name - item title
val - item content (HTML text)

outParameters

protected void outParameters(Parameter[] param,
                             String[] comments)
                      throws IOException
Description copied from class: MemberDoclet
Output parameters to the current documentandum (presumably a method).

Specified by:
outParameters in class MemberDoclet
Parameters:
param - array of Parameter objects
comments - array of comment strings matching params; if there's no comment, the element may be null
Throws:
IOException

outReturn

protected void outReturn(Type rtype,
                         String rdesc)
                  throws IOException
Description copied from class: MemberDoclet
Output return value for the current method.

Specified by:
outReturn in class MemberDoclet
Parameters:
rtype - type of return value
rdesc - text of return value description (may be null)
Throws:
IOException

outExamples

protected void outExamples(String[] examples)
Description copied from class: MemberDoclet
Output examples of the current documentandum (presumably a method).

Specified by:
outExamples in class MemberDoclet
Parameters:
examples - array of strings each representing an example

out

public void out(String[] lines)
         throws IOException
Outputs some lines of text to the current output stream. Implemented in terms of out(java.lang.String).

Parameters:
lines - text for output
Throws:
IOException

out

public void out(String line)
         throws IOException
Outputs a single line of output to the current output stream.

Parameters:
line - text for output
Throws:
IOException

flush

public void flush()
           throws IOException
Throws:
IOException

doctorText

public static String doctorText(String text)
Attempts to turn HTML text into XML. It's pretty ad-hoc, and many things can go wrong with it - using this relies on the various document tests picking up anything that goes wrong.

Parameters:
text - HTML-type text
Returns:
XML-type text


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.