.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "YARDOC 1"
.TH YARDOC 1 2024-03-03 0.9.36 ""
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
yardoc \- Ruby tool to generate documentation for the Ruby programming language
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fByarddoc\fR [\fIoptions\fR] [\fIsource_files\fR [\- \fIextra_files\fR]]
\&\fByard doc\fR [\fIoptions\fR] [\fIsource_files\fR [\- \fIextra_files\fR]]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fByard\fR(1) is an extensible documentation generation tool for the Ruby programming
language. It enables the user to generate consistent, usable documentation that
can be exported to a number of formats very easily, and also supports extending
for custom Ruby constructs such as custom class level definitions.
.PP
\&\fByardoc\fR, synonym for \fByard\fR \fBdoc\fR generates the documentation from the
list of \fIsource_files\fR. If this list is omitted, 
\&\f(CW\*(C`{lib,app}/**/*.rb ext/**/*.c\*(C'\fR is used.
.PP
A base set of options can be specified by adding a \fB.yardopts\fR
file to your base path containing all extra options separated
by whitespace.
.SH OPTIONS
.IX Header "OPTIONS"
.SS "General Options"
.IX Subsection "General Options"
.IP "\fB\-b\fR, \fB\-\-db\fR \fIFILE\fR" 4
.IX Item "-b, --db FILE"
Use a specified .yardoc db to load from or save to (defaults to .yardoc)
.IP \fB\-\-\fR[\fBno\-\fR]\fBsingle-db\fR 4
.IX Item "--[no-]single-db"
Whether code objects should be stored to single database file (advanced)
.IP "\fB\-n\fR, \fB\-\-no\-output\fR" 4
.IX Item "-n, --no-output"
Only generate .yardoc database, no documentation.
.IP "\fB\-c\fR, \fB\-\-use\-cache\fR [\fIFILE\fR]" 4
.IX Item "-c, --use-cache [FILE]"
Use the cached .yardoc db to generate documentation (defaults to no cache)
.IP \fB\-\-no\-cache\fR 4
.IX Item "--no-cache"
Clear .yardoc db before parsing source.
.IP "\fB\-\-\fR[\fBno\-\fR]\fByardopts\fR [\fIFILE\fR]" 4
.IX Item "--[no-]yardopts [FILE]"
If arguments should be read from FILE (defaults to yes, FILE defaults to .yardopts)
.IP \fB\-\-\fR[\fBno\-\fR]\fBdocument\fR 4
.IX Item "--[no-]document"
If arguments should be read from .document file (defaults to yes)
.IP \fB\-\-no\-save\fR 4
.IX Item "--no-save"
Do not save the parsed data to the yardoc db
.IP "\fB\-\-exclude\fR \fIREGEXP\fR" 4
.IX Item "--exclude REGEXP"
Ignores a file if it matches path match (regexp)
.SS "Output options"
.IX Subsection "Output options"
.IP \fB\-\-one\-file\fR 4
.IX Item "--one-file"
Generates output as a single file
.IP \fB\-\-list\fR 4
.IX Item "--list"
List objects to standard out (implies \fB\-n\fR)
.IP \fB\-\-no\-public\fR 4
.IX Item "--no-public"
Don't show public methods. (default shows public)
.IP \fB\-\-protected\fR 4
.IX Item "--protected"
Show protected methods. (default hides protected)
.IP \fB\-\-private\fR 4
.IX Item "--private"
Show private methods. (default hides private)
.IP \fB\-\-no\-private\fR 4
.IX Item "--no-private"
Hide objects with \f(CW@private\fR tag
.IP "\fB\-\-[no\-]api API\fR" 4
.IX Item "--[no-]api API"
Generates documentation for a given API (objects which define the correct \f(CW@api\fR tag).
If \fB\-\-no\-api\fR is given, displays objects with no \f(CW@api\fR tag.
.IP \fB\-\-embed\-mixins\fR 4
.IX Item "--embed-mixins"
Embeds mixin methods into class documentation
.IP "\fB\-\-embed\-mixin [MODULE]\fR" 4
.IX Item "--embed-mixin [MODULE]"
Embeds mixin methods from a particular module into class documentation
.IP \fB\-\-no\-highlight\fR 4
.IX Item "--no-highlight"
Don't highlight code blocks in output.
.IP "\fB\-\-default\-return TYPE\fR" 4
.IX Item "--default-return TYPE"
Shown if method has no return type.  (defaults to 'Object')
.IP \fB\-\-hide\-void\-return\fR 4
.IX Item "--hide-void-return"
Hides return types specified as 'void'.  (default is shown)
.IP "\fB\-\-query QUERY\fR" 4
.IX Item "--query QUERY"
Only show objects that match a specific query
.IP "\fB\-\-title TITLE\fR" 4
.IX Item "--title TITLE"
Add a specific title to HTML documents
.IP "\fB\-r\fR, \fB\-\-readme\fR, \fB\-\-main\fR \fIFILE\fR" 4
.IX Item "-r, --readme, --main FILE"
The readme file used as the title page of documentation.
.IP "\fB\-\-files\fR \fIFILE1\fR,\fIFILE2\fR,..." 4
.IX Item "--files FILE1,FILE2,..."
Any extra comma separated static files to be included (eg. FAQ)
.IP "\fB\-\-asset\fR \fIFROM\fR[:\fITO\fR]" 4
.IX Item "--asset FROM[:TO]"
A file or directory to copy over to output directory after generating
.IP "\fB\-o\fR, \fB\-\-output\-dir\fR \fIPATH\fR" 4
.IX Item "-o, --output-dir PATH"
The output directory. (defaults to ./doc)
.IP "\fB\-m\fR, \fB\-\-markup\fR \fBMARKUP\fR" 4
.IX Item "-m, --markup MARKUP"
Markup style used in documentation, like textile, markdown or rdoc (defaults to rdoc).
.IP "\fB\-M\fR \fIMARKUP_PROVIDER\fR" 4
.IX Item "-M MARKUP_PROVIDER"
Overrides the library used to process markup
.IP \fB\-\-markup\-provider\fR 4
.IX Item "--markup-provider"
formatting (specify the gem name)
.IP "\fB\-\-charset\fR \fIENC\fR" 4
.IX Item "--charset ENC"
Character set to use when parsing files (default is system locale)
.IP "\fB\-t\fR, \fB\-\-template\fR \fITEMPLATE\fR" 4
.IX Item "-t, --template TEMPLATE"
The template to use. (defaults to "default")
.IP "\fB\-p\fR, \fB\-\-template\-path\fR \fIPATH\fR" 4
.IX Item "-p, --template-path PATH"
The template path to look for templates in.  (used with \-t).
.IP "\fB\-f\fR, \fB\-\-format\fR \fIFORMAT\fR" 4
.IX Item "-f, --format FORMAT"
The output format for the template (defaults to html).
.IP \fB\-\-no\-stats\fR 4
.IX Item "--no-stats"
Don't print statistics
.IP "\fB\-\-locale\fR \fILOCALE\fR" 4
.IX Item "--locale LOCALE"
The locale for generated documentation (defaults to en).
.IP "\fB\-\-po\-dir\fR \fIDIR\fR" 4
.IX Item "--po-dir DIR"
The directory that has .po files (defaults to #{YARD::Registry.po_dir}).
.SS "Tag options:"
.IX Subsection "Tag options:"
(\fITAG\fR:\fITITLE\fR looks like: '\fBoverload\fR:\fBOverloaded Method\fR')
.IP "\fB\-\-tag\fR \fITAG\fR:\fITITLE\fR" 4
.IX Item "--tag TAG:TITLE"
Registers a new free-form metadata \f(CW@tag\fR
.IP "\fB\-\-type\-tag\fR \fITAG\fR:\fITITLE\fR" 4
.IX Item "--type-tag TAG:TITLE"
Tag with an optional types field
.IP "\fB\-\-type\-name\-tag\fR \fITAG\fR:\fITITLE\fR" 4
.IX Item "--type-name-tag TAG:TITLE"
Tag with optional types and a name field
.IP "\fB\-\-name\-tag\fR \fITAG\fR:\fITITLE\fR" 4
.IX Item "--name-tag TAG:TITLE"
Tag with a name field
.IP "\fB\-\-title\-tag\fR \fITAG\fR:\fITITLE\fR" 4
.IX Item "--title-tag TAG:TITLE"
Tag with first line as title field
.IP "\fB\-\-hide\-tag\fR \fITAG\fR" 4
.IX Item "--hide-tag TAG"
Hides a previously defined tag from templates
.IP "\fB\-\-transitive\-tag\fR \fITAG\fR" 4
.IX Item "--transitive-tag TAG"
Marks a tag as transitive
.IP "\fB\-\-non\-transitive\-tag\fR \fITAG\fR" 4
.IX Item "--non-transitive-tag TAG"
Marks a tag as not transitive
.SS "Other options:"
.IX Subsection "Other options:"
.IP "\fB\-e\fR, \fB\-\-load\fR \fIFILE\fR" 4
.IX Item "-e, --load FILE"
A Ruby script to load before running command.
.IP "\fB\-\-plugin\fR \fIPLUGIN\fR" 4
.IX Item "--plugin PLUGIN"
Load a YARD plugin (gem with `yard\-' prefix)
.IP \fB\-\-legacy\fR 4
.IX Item "--legacy"
Use old style Ruby parser and handlers. Always on in 1.8.x.
.IP \fB\-\-safe\fR 4
.IX Item "--safe"
Enable safe mode for this instance
.IP "\fB\-q\fR, \fB\-\-quiet\fR" 4
.IX Item "-q, --quiet"
Show no warnings.
.IP \fB\-\-verbose\fR 4
.IX Item "--verbose"
Show more information.
.IP \fB\-\-debug\fR 4
.IX Item "--debug"
Show debugging information.
.IP \fB\-\-backtrace\fR 4
.IX Item "--backtrace"
Show stack traces
.IP "\fB\-v\fR, \fB\-\-version\fR" 4
.IX Item "-v, --version"
Show version.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
Show this help.
.SH EXAMPLES
.IX Header "EXAMPLES"
\&\fByardoc\fR \fB\-o\fR \f(CW\*(C`documentation/\*(C'\fR \- \f(CW\*(C`FAQ\*(C'\fR \f(CW\*(C`LICENSE\*(C'\fR
.PP
The above example outputs documentation for files in
\&\f(CW\*(C`lib/**/*.rb\*(C'\fR to \f(CW\*(C`documentation/\*(C'\fR including the extra files
\&\f(CW\*(C`FAQ\*(C'\fR and \f(CW\*(C`LICENSE\*(C'\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fByard\fR(1).
.SH AUTHORS
.IX Header "AUTHORS"
\&\fByard\fR has been developed by Loren Segal <lsegal@soen.ca>.
.PP
This manual page has been written for the Debian Project by Cédric Boutillier (but
may used by others).