com.google.api.tools.framework.aspects.documentation.model

Class DocumentationUtil

java.lang.Object

com.google.api.tools.framework.aspects.documentation.model.DocumentationUtil

public class DocumentationUtil
extends java.lang.Object

Static utilities for dealing with documentation.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	asJsonString(java.lang.String text) Given a documentation string, escape it such that it can be represented as a JSON string.
static java.lang.String	filter(DiagCollector collector, java.util.Set<java.lang.String> visibilityLabels, Location location, java.lang.String source) Performs comment filtering.
static java.lang.String	getDeprecationDescription(ProtoElement element) Given an ProtoElement, returns its associated deprecation description.
static java.lang.String	getDescription(ProtoElement element) Given an ProtoElement, returns its associated description.
static java.lang.String	getDescription(ProtoElement element, java.lang.String defaultText) Given a proto element, returns its associated description.
static java.lang.String	getDocumentationRootUrl(Model model) Given a model, returns its associated documentation root url based on documentation and legacy configuration.
static java.lang.String	getScopedDescription(ProtoElement element) Get the description of the element scoped to the visibility as currently set in the model.
static java.lang.String	getScopedDescription(ProtoElement element, boolean reportWarning)
static java.util.List<com.google.api.Page>	getScopedToplevelPages(Model model) Get the documentation pages scoped to the visibility as currently set in the model.
static java.util.List<com.google.api.Page>	getToplevelPages(Model model) Get the documentation pages from given model.
static java.lang.String	removeCrossReference(java.lang.String text) Given a documentation string, replace the cross reference links with reference text.
static java.lang.String	rpcToRest(SymbolTable symbolTable, java.lang.String description) Given a string, searches for unqualified references to message fields and to method names and converts them from RPC-style to REST-style.

Methods inherited from class java.lang.Object

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

Method Detail

getToplevelPages

public static java.util.List<com.google.api.Page> getToplevelPages(Model model)

Get the documentation pages from given model.

getScopedToplevelPages

public static java.util.List<com.google.api.Page> getScopedToplevelPages(Model model)

Get the documentation pages scoped to the visibility as currently set in the model.

getDeprecationDescription

public static java.lang.String getDeprecationDescription(ProtoElement element)

Given an ProtoElement, returns its associated deprecation description. Returns the empty string if not available.

getDescription

public static java.lang.String getDescription(ProtoElement element)

Given an ProtoElement, returns its associated description. Returns the empty string if no description is available.

getScopedDescription

public static java.lang.String getScopedDescription(ProtoElement element)

Get the description of the element scoped to the visibility as currently set in the model.

getScopedDescription

public static java.lang.String getScopedDescription(ProtoElement element,
                                                    boolean reportWarning)

getDescription

public static java.lang.String getDescription(ProtoElement element,
                                              java.lang.String defaultText)

Given a proto element, returns its associated description. Returns defaultText if no description is available.

rpcToRest

public static java.lang.String rpcToRest(SymbolTable symbolTable,
                                         java.lang.String description)

Given a string, searches for unqualified references to message fields and to method names and converts them from RPC-style to REST-style. Field names are converted from lower_underscore to lowerCamel. Method names are converted from VerbCollection-style to collection.verb style. No work is done for qualified references; in such a case, an explicit markdown link with the proper display text should be used in the proto comment (e.g., [foo_bar][Path.To.Message.foo_bar], which will be converted to [fooBar][Path.To.Message.foo_bar] by rpcToRest).

getDocumentationRootUrl

public static java.lang.String getDocumentationRootUrl(Model model)

Given a model, returns its associated documentation root url based on documentation and legacy configuration. Returns empty string if not available.

asJsonString

public static java.lang.String asJsonString(java.lang.String text)

Given a documentation string, escape it such that it can be represented as a JSON string.

removeCrossReference

public static java.lang.String removeCrossReference(java.lang.String text)

Given a documentation string, replace the cross reference links with reference text.

filter

public static java.lang.String filter(DiagCollector collector,
                                      @Nullable
                                      java.util.Set<java.lang.String> visibilityLabels,
                                      Location location,
                                      @Nullable
                                      java.lang.String source)

Performs comment filtering. Parse the text to remove non visible comments enclosed by "(-- --)" tags. It works as follows:

• All leading and trailing white spaces surrounding tags will be replaced with one space. For example:

     "Foo (-- internal --) foo"
     will be returned as
     "Foo foo"
   

  Except, if internal comment is at the beginning of the line, no space will be inserted. For example:

     "(-- internal --) foo"
     will be returned as
     "foo"
   

• Lines with only internal comments (all text enclosed by tags) will be removed. For example:

     "Foo (-- internal --)
     (-- internal --) (-- internal2 --)
     Foo"
     will be returned as
     "Foo
     Foo"
   

• If visibility label "(--LABEL: ... --) is specified, the comments will be kept if the label is found in the provided visibility labels. If no label was specified, the comments will be filtered.
• Nested tags are valid, but should appear in pair.
• It only reports the first encountered error if multiple ones exist.
• Tags may be escaped with a backslash, for example, "\(-- ... \--)".