# Class DocUtils

java.lang.Object
uk.ac.starlink.ttools.DocUtils

public class DocUtils extends Object
Utilities used for automatically-generated documentation.

Since:
  27 Sep 2006
Author:
  Mark Taylor

## Method Summary

Modifier and Type
Method
Description
`static <E> String`
`describedList(E[] items, Function<E,String> namer, Function<E,String> describer, boolean isDescriptionXml)`
Returns a XML string listing an array of objects with names and descriptions.
`static <E> String`
`describedList(Collection<E> items, Function<E,String> namer, Function<E,String> describer, boolean isDescriptionXml)`
Returns a XML string listing an array of objects with names and descriptions.
`static String`
`filterRef(BasicFilter filter)`
Provides a snippet of XML which references a processing filter.
`static String`
`fromXhtml(String xhtml)`
Does minimal conversion from XHTML-like XML to SUN-friendly XML.
`static String`
`getXmlDescription(uk.ac.starlink.table.Documented item)`
Returns the XML description provided by an item implementing the Documented interface, in a form suitable for insertion into the STILTS user document.
`static String`
`join(String[] lines)`
Concatenates an array of strings, appending a carriage return to each one.
`static String`
`listInfos(uk.ac.starlink.table.ValueInfo[] infos)`
Returns a string listing the supplied array of metadata objects.
`static String`
`modeRef(String name)`
Provides a snippet of XML which references a named `ProcessingMode`.

### Methods inherited from class Object

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

## Method Details

### join

public static String join(String[] lines)
Concatenates an array of strings, appending a carriage return to each one.

Parameters:
  `lines` - array of input strings
Returns:
  one long output string

### filterRef

public static String filterRef(BasicFilter filter)
Provides a snippet of XML which references a processing filter.

Parameters:
  `filter` - processing filter
Returns:
  filter reference

### modeRef

public static String modeRef(String name)
Provides a snippet of XML which references a named `ProcessingMode`.

Parameters:
  `name` - mode name
Returns:
  mode reference

### listInfos

public static String listInfos(uk.ac.starlink.table.ValueInfo[] infos)
Returns a string listing the supplied array of metadata objects. The returned string should be suitable for inserting into XML text.

Parameters:
  `infos` - array of infos
Returns:
  string listing `infos` by name

### describedList

public static <E> String describedList(E[] items, Function<E,String> namer, Function<E,String> describer, boolean isDescriptionXml)
Returns a XML string listing an array of objects with names and descriptions. The output is a `<ul>` element.

This is a convenience wrapper for the overloaded method that takes a `Collection<E>`.

Parameters:
  `items` - objects to list
  `namer` - maps object to object name
  `describer` - maps object to object description
  `isDescriptionXml` - if true, the description text may contain XML formatting, and should be inserted into the output as is; if false, any magic characters will be escaped as required for XML
Returns:
  xml list

### describedList

public static <E> String describedList(Collection<E> items, Function<E,String> namer, Function<E,String> describer, boolean isDescriptionXml)
Returns a XML string listing an array of objects with names and descriptions. The output is a `<ul>` element.

Parameters:
  `items` - objects to list
  `namer` - maps object to object name
  `describer` - maps object to object description
  `isDescriptionXml` - if true, the description text may contain XML formatting, and should be inserted into the output as is; if false, any magic characters will be escaped as required for XML
Returns:
  xml list

### getXmlDescription

public static String getXmlDescription(uk.ac.starlink.table.Documented item) throws IOException
Returns the XML description provided by an item implementing the Documented interface, in a form suitable for insertion into the STILTS user document.

Note the implementation of this is currently somewhat scrappy; it works on the things that it's called upon to transform during the STILTS user document build, but it may need extra work if some less constrained XHTML gets fed to it. If that becomes the case, problems should show up at TTOOLS package build/test time.

Parameters:
  `item` - supplier of (XHTML-like) documentation XML
Returns:
  SUN-compliant XML
Throws:
  `IOException`

### fromXhtml

public static String fromXhtml(String xhtml) throws IOException, TransformerException
Does minimal conversion from XHTML-like XML to SUN-friendly XML. Since this works on strings, it's not intended for huge documents.

Parameters:
  `xhtml` - input XHTML-like XML string, expected to be a sequence of P elements
Returns:
  output SUN-friendly XML string
Throws:
  `IOException`
  `TransformerException`