uk.ac.starlink.ttools.build

Class XmlDocletOutput

java.lang.Object

uk.ac.starlink.ttools.build.XmlDocletOutput

All Implemented Interfaces:

DocletOutput

public class XmlDocletOutput
extends Object
implements DocletOutput

DocletOutput implementation for writing SUN-friendly XML. The output is intended to be inserted into TOPCAT/STILTS user documents to document the user-visible expressions in the JEL expression language.

Since:

24 Jan 2023

Author:

Mark Taylor

Nested Class Summary

Nested classes/interfaces inherited from interface uk.ac.starlink.ttools.build.DocletOutput

DocletOutput.DocVariable

Constructor Summary

Constructors

Constructor and Description
XmlDocletOutput(OutputStream out, boolean headOnly, java.util.function.Function<String,String> clazzToId) Constructor.

Method Summary

Modifier and Type	Method and Description
void	endClass() End output of documentation for the most recently started class.
void	endMember() End output of the most recently started member.
void	endOutput() Called at the end of operation.
void	outExamples(String heading, String[] examples) Writes one or more example entries.
void	outMemberItem(String name, String val) This information is discarded; the XML output is too terse to include it.
void	outParameters(DocletOutput.DocVariable[] params) Writes a description of the parameters of a method.
void	outReturn(String type, String comment) Writes information about the return value of a method.
void	outSees(String heading, String[] sees) Writes one or more See Also entries.
void	startClass(String className, String firstSentence, String fullDescription) Begin output of documentation for a given class.
void	startMember(String memberName, String memberType, String memberId, String description) Begin output of documentation for a given class member (field or method).
void	startOutput() Called at the start of operation.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XmlDocletOutput

public XmlDocletOutput(OutputStream out,
                       boolean headOnly,
                       java.util.function.Function<String,String> clazzToId)

Constructor.

Parameters:

out - destination stream

headOnly - if true, only a short summary of each class will be written

clazzToId - maps fully-qualified classname to the (base) XML ID that will be used for that class in the XML output

Method Detail

startOutput

public void startOutput()
                 throws IOException

Description copied from interface: DocletOutput

Called at the start of operation.

Specified by:

startOutput in interface DocletOutput

Throws:

IOException

endOutput

public void endOutput()
               throws IOException

Description copied from interface: DocletOutput

Called at the end of operation.

Specified by:

endOutput in interface DocletOutput

Throws:

IOException

startClass

public void startClass(String className,
                       String firstSentence,
                       String fullDescription)
                throws IOException

Description copied from interface: DocletOutput

Begin output of documentation for a given class.

Specified by:

startClass in interface DocletOutput

Parameters:

className - fully qualified class name

firstSentence - first sentence of class description, in HTML

fullDescription - full text of class description, in HTML

Throws:

IOException

endClass

public void endClass()
              throws IOException

Description copied from interface: DocletOutput

End output of documentation for the most recently started class.

Specified by:

endClass in interface DocletOutput

Throws:

IOException

startMember

public void startMember(String memberName,
                        String memberType,
                        String memberId,
                        String description)
                 throws IOException

Description copied from interface: DocletOutput

Begin output of documentation for a given class member (field or method).

Specified by:

startMember in interface DocletOutput

Parameters:

memberName - user-readable name of the member

memberType - some user-readable (maybe avoiding technical terms) description of what kind of member it is

memberId - string uniquely identifying this member within its parent class

description - full text of member description, in HTML

Throws:

IOException

endMember

public void endMember()
               throws IOException

Description copied from interface: DocletOutput

End output of the most recently started member.

Specified by:

endMember in interface DocletOutput

Throws:

IOException

outMemberItem

public void outMemberItem(String name,
                          String val)
                   throws IOException

This information is discarded; the XML output is too terse to include it.

Specified by:

outMemberItem in interface DocletOutput

Parameters:

name - item name

val - item value, may be HTML

Throws:

IOException

outParameters

public void outParameters(DocletOutput.DocVariable[] params)
                   throws IOException

Description copied from interface: DocletOutput

Writes a description of the parameters of a method.

Specified by:

outParameters in interface DocletOutput

Parameters:

params - parameter list

Throws:

IOException

outReturn

public void outReturn(String type,
                      String comment)
               throws IOException

Description copied from interface: DocletOutput

Writes information about the return value of a method.

Specified by:

outReturn in interface DocletOutput

Parameters:

type - return type specification for presentation to the user

comment - description of returned value, may be HTML

Throws:

IOException

outExamples

public void outExamples(String heading,
                        String[] examples)
                 throws IOException

Description copied from interface: DocletOutput

Writes one or more example entries.

Specified by:

outExamples in interface DocletOutput

Parameters:

heading - heading for examples section

examples - list of example lines, may be HTML

Throws:

IOException

outSees

public void outSees(String heading,
                    String[] sees)
             throws IOException

Description copied from interface: DocletOutput

Writes one or more See Also entries.

Specified by:

outSees in interface DocletOutput

Parameters:

heading - heading for See Also section

sees - list of entries, may be HTML

Throws:

IOException