Package epydoc :: Package markup :: Module javadoc :: Class ParsedJavadocDocstring

[hide private]
[frames] | no frames]

# Class ParsedJavadocDocstring

source code

An encoded version of a Javadoc docstring. Since Javadoc is a fairly simple markup language, we don't do any processing in advance; instead, we wait to split fields or resolve crossreference links until we need to.

Instance Methods | [hide private]

__init__(self, docstring, errors=None) Create a new `ParsedJavadocDocstring`. | source code

_check_links(self, errors) Make sure that all @{link}s are valid. | source code

`string`

to_plaintext(self, docstring_linker, **options) Translate this docstring to plaintext. | source code

(ParsedDocstring, `bool`)

summary(self) Returns: A pair consisting of a short summary of this docstring and a boolean value indicating whether there is further documentation in addition to the summary. | source code

Inherited from `ParsedDocstring`: `__add__`, `concatenate`, `index_terms`, `to_latex`
Field Splitting

`(ParsedDocstring, list of Field)`

split_fields(self, errors=None) Split this docstring into its body and its fields. | source code

HTML Output

`string`

to_html(self, docstring_linker, **options) Translate this docstring to HTML. | source code

Class Variables | [hide private]

| _SUMMARY_RE = `re.compile(r'`(`\s`*``[`\w\W`]``*?`\.`)``(`\s`|`$`)`')`
Field Splitting
| _ARG_FIELDS = ``[``'``group``'``,` `'``variable``'``,` `'``var``'``,` `'``type``'``,` `'``cvariable``'``...`` A list of the fields that take arguments.
| _FIELD_RE = `re.compile(r'`(?m)``(`^\s`*`@\w`+``[`\s\$`]``)`')` A regular expression used to search for Javadoc block tags.
HTML Output
| _LINK_SPLIT_RE = `re.compile(r'`(`\{@link`(?:`plain`)``?`\s`[^`\}`]``+`\}`)`')` A regular expression used to search for Javadoc inline tags.
| _LINK_RE = `re.compile(r'\{@link`(?:`plain`)``?`\s`+``(``[`\w#\.`]``+``)``(?:`\(`[^`\`...`` A regular expression used to process Javadoc inline tags.

Method Details | [hide private]

### __init__(self, docstring, errors=None)
(Constructor)

source code

Create a new `ParsedJavadocDocstring`.

Parameters:
  - `docstring` (`string`) - The docstring that should be used to construct this `ParsedJavadocDocstring`.
  - `errors` (`list` of ParseError) - A list where any errors generated during parsing will be stored. If no list is given, then all errors are ignored.

### split_fields(self, errors=None)

source code

Split this docstring into its body and its fields.

Parameters:
  - `errors` - A list where any errors generated during splitting will be stored. If no list is specified, then errors will be ignored.
Returns: `(ParsedDocstring, list of Field)`
  A tuple `(body, fields)`, where `body` is the main body of this docstring, and `fields` is a list of its fields. If the resulting body is empty, return `None` for the body.
Overrides: ParsedDocstring.split_fields
  (inherited documentation)

### to_html(self, docstring_linker, **options)

source code

Translate this docstring to HTML.

Parameters:
  - `docstring_linker` - An HTML translator for crossreference links into and out of the docstring.
  - `options` - Any extra options for the output. Unknown options are ignored.
Returns: `string`
  An HTML fragment that encodes this docstring.
Overrides: ParsedDocstring.to_html
  (inherited documentation)

### _check_links(self, errors)

source code

Make sure that all @{link}s are valid. We need a separate method for ths because we want to do this at parse time, not html output time. Any errors found are appended to `errors`.

### to_plaintext(self, docstring_linker, **options)

source code

Translate this docstring to plaintext.

Parameters:
  - `docstring_linker` - A plaintext translator for crossreference links into and out of the docstring.
  - `options` - Any extra options for the output. Unknown options are ignored.
Returns: `string`
  A plaintext fragment that encodes this docstring.
Overrides: ParsedDocstring.to_plaintext
  (inherited documentation)

### summary(self)

source code

Returns: (ParsedDocstring, `bool`)
  A pair consisting of a short summary of this docstring and a boolean value indicating whether there is further documentation in addition to the summary. Typically, the summary consists of the first sentence of the docstring.
Overrides: ParsedDocstring.summary
  (inherited documentation)

Class Variable Details | [hide private]

### _ARG_FIELDS

A list of the fields that take arguments. Since Javadoc doesn't mark arguments in any special way, we must consult this list to decide whether the first word of a field is an argument or not.

Value:

      ['group',
       'variable',
       'var',
       'type',
       'cvariable',
       'cvar',
       'ivariable',
       'ivar',
      ...

### _LINK_RE

A regular expression used to process Javadoc inline tags.

Value:

      re.compile(r'\{@link(?:plain)?\s+([\w#\.]+)(?:\([^\)]*\))?(\s+.*)?\}')