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 
    Characterises a method parameter.
  • Method Summary

    Modifier and Type
    Method
    Description
    void
    End output of documentation for the most recently started class.
    void
    End output of the most recently started member.
    void
    Called at the end of operation.
    void
    outExamples(String heading, String[] examples)
    Writes one or more example entries.
    void
    Writes a name-value pair presenting an attribute of a class member (field or method).
    void
    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
    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