module watt.text.vdoc

Volt doccomment parsing and cleaning code.

VDoc is Volt's default doccomment format. This modules provides utilities for parsing VDoc strings.

Code Map

//! Volt doccomment parsing and cleaning code.
module watt.text.vdoc;


enum DocState
{
	Content,
	Brief,
	Param,
	Section,
}

enum DocSection
{
	SeeAlso,
	Return,
	SideEffect,
	Throw,
}

//! Interface for doc string consumers.
interface DocSink
{
public:
	//! Signals the start of the full content.
	fn start(sink: scope (Sink));
	//! Signals the end of the full content.
	fn end(sink: scope (Sink));
	//! Signals the start of a brief comment section.
	fn briefStart(sink: scope (Sink));
	//! Signals the end of a brief comment section.
	fn briefEnd(sink: scope (Sink));
	//! Signals the start of a param comment section.
	fn paramStart(sink: scope (Sink), direction: string, arg: string);
	//! Signals the end of a param comment section.
	fn paramEnd(sink: scope (Sink));
	//! Signals the start of a section, these are never nested.
	fn sectionStart(sink: scope (Sink), sec: DocSection);
	//! Signals the end of a section, these are never nested.
	fn sectionEnd(sink: scope (Sink), sec: DocSection);
	//! Regular text content.
	fn content(sink: scope (Sink), state: DocState, d: string);
	//! p comment section.
	fn p(sink: scope (Sink), state: DocState, d: string);
	//! link comment section.
	fn link(sink: scope (Sink), state: DocState, target: string, text: string);
	//! The defgroup command.
	fn defgroup(sink: scope (Sink), group: string, text: string);
	//! The ingroup command, may get called multiple times.
	fn ingroup(sink: scope (Sink), group: string);
}

//! Take a doc comment and remove comment cruft from it.
fn cleanComment(comment: string, isBackwardsComment: bool) string { }
//! Given a doc string input, call dsink methods with the given sink as an
//! argument.
fn parse(src: string, dsink: DocSink, sink: scope (Sink)) { }

fn cleanComment(comment: string, isBackwardsComment: bool) string

Take a doc comment and remove comment cruft from it.

'Comment cruft' are things like *, +, and / for their respective comment types.

interface DocSink

Interface for doc string consumers.

Implement this class, and pass an instance of your implementation to the parse function.

fn start(sink: scope (Sink))

Signals the start of the full content.

fn end(sink: scope (Sink))

Signals the end of the full content.

fn briefStart(sink: scope (Sink))

Signals the start of a brief comment section.

fn briefEnd(sink: scope (Sink))

Signals the end of a brief comment section.

fn paramStart(sink: scope (Sink), direction: string, arg: string)

Signals the start of a param comment section.

fn paramEnd(sink: scope (Sink))

Signals the end of a param comment section.

fn sectionStart(sink: scope (Sink), sec: DocSection)

Signals the start of a section, these are never nested.

fn sectionEnd(sink: scope (Sink), sec: DocSection)

Signals the end of a section, these are never nested.

fn content(sink: scope (Sink), state: DocState, d: string)

Regular text content.

fn p(sink: scope (Sink), state: DocState, d: string)

p comment section.

fn link(sink: scope (Sink), state: DocState, target: string, text: string)

link comment section.

fn defgroup(sink: scope (Sink), group: string, text: string)

The defgroup command.

fn ingroup(sink: scope (Sink), group: string)

The ingroup command, may get called multiple times.

fn parse(src: string, dsink: DocSink, sink: scope (Sink))

Given a doc string input, call dsink methods with the given sink as an argument.

The sink argument can be passed as a convenience -- it may be null.

Example

ds: YourDocSinkImplementation;
parse("`hello`", ds, sink);  // ds.start, ds.p, and ds.end, will be called.

struct Parser

Internal private parser struct.

fn commandLoop(p: Parser, sink: scope (Sink))

Loop over src, calling contentDg as appropriate, and handleCommand for commands.

fn isBreakingCommand(command: string) bool

Does the given command break a paragraph.

fn handleCommand(p: Parser, sink: scope (Sink), command: string) bool

Dispatch a command to its handler. Returns: true if handled.

fn handleCommandP(p: Parser, sink: scope (Sink))

Parse an p command.

fn handleCommandRef(p: Parser, sink: scope (Sink))

Parse an ref command.

fn handleCommandLink(p: Parser, sink: scope (Sink))

Parse an link command.

fn handleCommandSection(p: Parser, sink: scope (Sink), sec: DocSection)

Parse a generic section command.

fn handleCommandParam(p: Parser, sink: scope (Sink), direction: string)

Parse an param command.

fn handleCommandBrief(p: Parser, sink: scope (Sink))

Parse an brief command.

fn handleCommandDefGroup(p: Parser, sink: scope (Sink))

Parse an defgroup command.

fn handleCommandInGroup(p: Parser, sink: scope (Sink))

Parse an ingroup command.

fn getParagraph(src: SimpleSource) string

Decode until we're at the end of the string, or an empty line.

fn getWord(src: SimpleSource) string

Decode until we're at the end of the string, or a non word character.

fn getThing(src: SimpleSource) string

Decode until we're at the end of the string, or a non thing character.

A thing is very loosely defined as a character string that could be an ident or a type. So f32[4] is a thing, as is arr[4].field. But from foo. only foo is a thing, notice that the trailing . is not included.

fn getRestOfLine(src: SimpleSource) string

Get the rest of this line, newline is included.

fn getLinkWord(src: SimpleSource) string

Get a link word, alpha num with dots in them.

Trailing dots are not included.

fn isFrontLinkWord(src: SimpleSource) bool

My we are awfully specific.

fn eatWhitespace(src: SimpleSource)

Decode until we're at the end of the string, or a non isWhite character.

fn decodeUntil(src: SimpleSource, cond: bool delegate(dchar)) string

Decode until cond is true, or we're out of string.