Package epydoc :: Package markup :: Module javadoc

[hide private]
[frames] | no frames]

# Module javadoc

source code

Epydoc parser for Javadoc docstrings. Javadoc is an HTML-based markup language that was developed for documenting Java APIs with inline comments. It consists of raw HTML, augmented by Javadoc tags. There are two types of Javadoc tag:

- Javadoc block tags correspond to Epydoc fields. They are marked by starting a line with a string of the form "`@tag [arg]`", where `tag` indicates the type of block, and `arg` is an optional argument. (For fields that take arguments, Javadoc assumes that the single word immediately following the tag is an argument; multi-word arguments cannot be used with javadoc.)
- inline Javadoc tags are used for inline markup. In particular, epydoc uses them for crossreference links between documentation. Inline tags may appear anywhere in the text, and have the form "`{@tag [args...]}`", where `tag` indicates the type of inline markup, and `args` are optional arguments.

Epydoc supports all Javadoc tags, except:

- `{@docRoot}`, which gives the (relative) URL of the generated documentation's root.
- `{@inheritDoc}`, which copies the documentation of the nearest overridden object. This can be used to combine the documentation of the overridden object with the documentation of the overridding object.
- `@serial`, `@serialField`, and `@serialData` which describe the serialization (pickling) of an object.
- `{@value}`, which copies the value of a constant.

Warning: Epydoc only supports HTML output for Javadoc docstrings.

Classes | [hide private]

| ParsedJavadocDocstring An encoded version of a Javadoc docstring.

Functions | [hide private]

ParsedDocstring

parse_docstring(docstring, errors, **options) Parse the given docstring, which is formatted using Javadoc; and return a `ParsedDocstring` representation of its contents. | source code

Function Details | [hide private]

### parse_docstring(docstring, errors, **options)

source code

Parse the given docstring, which is formatted using Javadoc; and return a `ParsedDocstring` representation of its contents.

Parameters:
  - `docstring` (`string`) - The docstring to parse
  - `errors` (`list` of ParseError) - A list where any errors generated during parsing will be stored.
  - `options` - Extra options. Unknown options are ignored. Currently, no extra options are defined.
Returns: ParsedDocstring