uk.ac.starlink.ttools.build

Interface DocletOutput

All Known Implementing Classes:

HtmlDocletOutput, XmlDocletOutput

public interface DocletOutput

Serializes text obtained from javadocs to some specific output format.

This interface is intended for working with the classes providing functionality made available through the JEL expression language. The methods have been introduced ad hoc to provide the functionality required for that purpose, and do not intend to form a comprehensive doclet output interface.

Since this interface is only intended for use at package build time, and since the classes it works with have conservatively-written javadocs, implementations do not need to be robust against all possible input. In case of problems however they should warn or fail noisily rather than produce sub-standard best-efforts output.

This interface makes no use of any javadoc API. Its purpose is to act as a format-specific output handler that is not tied to a particular javadoc parsing API.

Since:

24 Jan 2023

Author:

Mark Taylor

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	DocletOutput.DocVariable Characterises a method parameter.

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 key, String value) Writes a name-value pair presenting an attribute of a class member (field or method).
void	outParameters(DocletOutput.DocVariable[] params) Writes a description of the parameters of a method.
void	outReturn(String type, String commentText) 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 name, String type, String memberId, String description) Begin output of documentation for a given class member (field or method).
void	startOutput() Called at the start of operation.

Method Detail

startOutput

void startOutput()
          throws IOException

Called at the start of operation.

Throws:

IOException

endOutput

void endOutput()
        throws IOException

Called at the end of operation.

Throws:

IOException

startClass

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

Begin output of documentation for a given class.

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

void endClass()
       throws IOException

End output of documentation for the most recently started class.

Throws:

IOException

startMember

void startMember(String name,
                 String type,
                 String memberId,
                 String description)
          throws IOException

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

Parameters:

name - user-readable name of the member

type - 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

void endMember()
        throws IOException

End output of the most recently started member.

Throws:

IOException

outMemberItem

void outMemberItem(String key,
                   String value)
            throws IOException

Writes a name-value pair presenting an attribute of a class member (field or method).

Parameters:

key - item name

value - item value, may be HTML

Throws:

IOException

outParameters

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

Writes a description of the parameters of a method.

Parameters:

params - parameter list

Throws:

IOException

outReturn

void outReturn(String type,
               String commentText)
        throws IOException

Writes information about the return value of a method.

Parameters:

type - return type specification for presentation to the user

commentText - description of returned value, may be HTML

Throws:

IOException

outExamples

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

Writes one or more example entries.

Parameters:

heading - heading for examples section

examples - list of example lines, may be HTML

Throws:

IOException

outSees

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

Writes one or more See Also entries.

Parameters:

heading - heading for See Also section

sees - list of entries, may be HTML

Throws:

IOException