# 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
Description
`static interface`
`DocletOutput.DocVariable`
Characterises a method parameter.

## Method Summary

Modifier and Type
Method
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 Details

### 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`