/usr/share/doc/yard/doc/index.html is in yard-doc 0.9.12-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 | <!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: README
— YARD 0.9.12 Documentation
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
pathId = "README";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="class_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'><h1>YARD: Yay! A Ruby Documentation Tool</h1>
<h2>Synopsis</h2>
<p>YARD is a 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. Below is a
summary of some of YARD's notable features.</p>
<h2>Feature List</h2>
<p><strong>1. RDoc/SimpleMarkup Formatting Compatibility</strong>: YARD is made to be compatible
with RDoc formatting. In fact, YARD does no processing on RDoc documentation
strings, and leaves this up to the output generation tool to decide how to
render the documentation.</p>
<p><strong>2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages</strong>:
YARD uses a '@tag' style definition syntax for meta tags alongside regular code
documentation. These tags should be able to happily sit side by side RDoc formatted
documentation, but provide a much more consistent and usable way to describe
important information about objects, such as what parameters they take and what types
they are expected to be, what type a method should return, what exceptions it can
raise, if it is deprecated, etc.. It also allows information to be better (and more
consistently) organized during the output generation phase. You can find a list
of tags in the <a href="file.Tags.html#taglist" title="Tags.md">Tags.md</a> file.</p>
<p>YARD also supports an optional "types" declarations for certain tags.
This allows the developer to document type signatures for ruby methods and
parameters in a non intrusive but helpful and consistent manner. Instead of
describing this data in the body of the description, a developer may formally
declare the parameter or return type(s) in a single line. Consider the
following method documented with YARD formatting:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># Reverses the contents of a String or IO object.
</span><span class='comment'>#
</span><span class='comment'># @param [String, #read] contents the contents to reverse
</span><span class='comment'># @return [String] the contents reversed lexically
</span><span class='kw'>def</span> <span class='id identifier rubyid_reverse'>reverse</span><span class='lparen'>(</span><span class='id identifier rubyid_contents'>contents</span><span class='rparen'>)</span>
<span class='id identifier rubyid_contents'>contents</span> <span class='op'>=</span> <span class='id identifier rubyid_contents'>contents</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span> <span class='kw'>if</span> <span class='id identifier rubyid_contents'>contents</span><span class='period'>.</span><span class='id identifier rubyid_respond_to?'>respond_to?</span> <span class='symbol'>:read</span>
<span class='id identifier rubyid_contents'>contents</span><span class='period'>.</span><span class='id identifier rubyid_reverse'>reverse</span>
<span class='kw'>end</span>
</code></pre>
<p>With the above @param tag, we learn that the contents parameter can either be
a String or any object that responds to the 'read' method, which is more
powerful than the textual description, which says it should be an IO object.
This also informs the developer that they should expect to receive a String
object returned by the method, and although this may be obvious for a
'reverse' method, it becomes very useful when the method name may not be as
descriptive.</p>
<p><strong>3. Custom Constructs and Extensibility of YARD</strong>: YARD is designed to be
extended and customized by plugins. Take for instance the scenario where you
need to document the following code:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>List</span>
<span class='comment'># Sets the publisher name for the list.
</span> <span class='id identifier rubyid_cattr_accessor'>cattr_accessor</span> <span class='symbol'>:publisher</span>
<span class='kw'>end</span>
</code></pre>
<p>This custom declaration provides dynamically generated code that is hard for a
documentation tool to properly document without help from the developer. To
ease the pains of manually documenting the procedure, YARD can be extended by
the developer to handle the <code>cattr_accessor</code> construct and automatically create
an attribute on the class with the associated documentation. This makes
documenting external API's, especially dynamic ones, a lot more consistent for
consumption by the users.</p>
<p>YARD is also designed for extensibility everywhere else, allowing you to add
support for new programming languages, new data structures and even where/how
data is stored.</p>
<p><strong>4. Raw Data Output</strong>: YARD also outputs documented objects as raw data (the
dumped Namespace) which can be reloaded to do generation at a later date, or
even auditing on code. This means that any developer can use the raw data to
perform output generation for any custom format, such as YAML, for instance.
While YARD plans to support XHTML style documentation output as well as
command line (text based) and possibly XML, this may still be useful for those
who would like to reap the benefits of YARD's processing in other forms, such
as throwing all the documentation into a database. Another useful way of
exploiting this raw data format would be to write tools that can auto generate
test cases, for example, or show possible unhandled exceptions in code.</p>
<p><strong>5. Local Documentation Server</strong>: YARD can serve documentation for projects
or installed gems (similar to <code>gem server</code>) with the added benefit of dynamic
searching, as well as live reloading. Using the live reload feature, you can
document your code and immediately preview the results by refreshing the page;
YARD will do all the work in re-generating the HTML. This makes writing
documentation a much faster process.</p>
<h2>Installing</h2>
<p>To install YARD, use the following command:</p>
<pre class="code sh"><code class="sh">$ gem install yard
</code></pre>
<p>(Add <code>sudo</code> if you're installing under a POSIX system as root)</p>
<p>Alternatively, if you've checked the source out directly, you can call
<code>rake install</code> from the root project directory.</p>
<p><strong>Important Note for Debian/Ubuntu users:</strong> there's a possible chance your Ruby
install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
If running <code>which rdoc</code> turns up empty, install RDoc by issuing:</p>
<pre class="code sh"><code class="sh">$ sudo apt-get install rdoc
</code></pre>
<h2>Usage</h2>
<p>There are a couple of ways to use YARD. The first is via command-line, and the
second is the Rake task.</p>
<p><strong>1. yard Command-line Tool</strong></p>
<p>YARD comes packaged with a executable named <code>yard</code> which can control the many
functions of YARD, including generating documentation, graphs running the
YARD server, and so on. To view a list of available YARD commands, type:</p>
<pre class="code sh"><code class="sh">$ yard --help
</code></pre>
<p>Plugins can also add commands to the <code>yard</code> executable to provide extra
functionality.</p>
<h3>Generating Documentation</h3>
<p><span class="note">The <code>yardoc</code> executable is a shortcut for <code>yard doc</code>.</span></p>
<p>The most common command you will probably use is <code>yard doc</code>, or <code>yardoc</code>. You
can type <code>yardoc --help</code> to see the options that YARD provides, but the
easiest way to generate docs for your code is to simply type <code>yardoc</code> in your
project root. This will assume your files are
located in the <code>lib/</code> directory. If they are located elsewhere, you can specify
paths and globs from the commandline via:</p>
<pre class="code sh"><code class="sh">$ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
</code></pre>
<p>The tool will generate a <code>.yardoc</code> file which will store the cached database
of your source code and documentation. If you want to re-generate your docs
with another template you can simply use the <code>--use-cache</code> (or -c)
option to speed up the generation process by skipping source parsing.</p>
<p>YARD will by default only document code in your public visibility. You can
document your protected and private code by adding <code>--protected</code> or
<code>--private</code> to the option switches. In addition, you can add <code>--no-private</code>
to also ignore any object that has the <code>@private</code> meta-tag. This is similar
to RDoc's ":nodoc:" behaviour, though the distinction is important. RDoc
implies that the object with :nodoc: would not be documented, whereas
YARD still recommends documenting private objects for the private API (for
maintainer/developer consumption).</p>
<p>You can also add extra informative files (README, LICENSE) by separating
the globs and the filenames with '-'.</p>
<pre class="code sh"><code class="sh">$ yardoc 'app/**/*.rb' - README LICENSE FAQ
</code></pre>
<p>If no globs precede the '-' argument, the default glob (<code>lib/**/*.rb</code>) is
used:</p>
<pre class="code sh"><code class="sh">$ yardoc - README LICENSE FAQ
</code></pre>
<p>Note that the README file can be specified with its own <code>--readme</code> switch.</p>
<p>You can also add a <code>.yardopts</code> file to your project directory which lists
the switches separated by whitespace (newlines or space) to pass to yardoc
whenever it is run. A full overview of the <code>.yardopts</code> file can be found in
<span class='object_link'><a href="YARD/CLI/Yardoc.html" title="YARD::CLI::Yardoc (class)">YARD::CLI::Yardoc</a></span>.</p>
<h3>Queries</h3>
<p>The <code>yardoc</code> tool also supports a <code>--query</code> argument to only include objects
that match a certain data or meta-data query. The query syntax is Ruby, though
a few shortcuts are available. For instance, to document only objects that have
an "@api" tag with the value "public", all of the following syntaxes would give
the same result:</p>
<pre class="code sh"><code class="sh">--query '@api.text == "public"'
--query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
--query 'has_tag?(:api) && tag(:api).text == "public"'
</code></pre>
<p>Note that the "@tag" syntax returns the first tag named "tag" on the object.
To return the array of all tags named "tag", use "@@tag".</p>
<p>Multiple <code>--query</code> arguments are allowed in the command line parameters. The
following two lines both check for the existence of a return and param tag:</p>
<pre class="code sh"><code class="sh">--query '@return' --query '@param'
--query '@return && @param'
</code></pre>
<p>For more information about the query syntax, see the <span class='object_link'><a href="YARD/Verifier.html" title="YARD::Verifier (class)">YARD::Verifier</a></span> class.</p>
<p><strong>2. Rake Task</strong></p>
<p>The second most obvious is to generate docs via a Rake task. You can do this by
adding the following to your <code>Rakefile</code>:</p>
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="YARD.html" title="YARD (module)">YARD</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="YARD/Rake.html" title="YARD::Rake (module)">Rake</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="YARD/Rake/YardocTask.html" title="YARD::Rake::YardocTask (class)">YardocTask</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="YARD/Rake/YardocTask.html#initialize-instance_method" title="YARD::Rake::YardocTask#initialize (method)">new</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_t'>t</span><span class='op'>|</span>
<span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_files'>files</span> <span class='op'>=</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>lib/**/*.rb</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='const'>OTHER_PATHS</span><span class='rbracket'>]</span> <span class='comment'># optional
</span> <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_options'>options</span> <span class='op'>=</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--any</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--extra</span><span class='tstring_end'>'</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--opts</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'># optional
</span> <span class='id identifier rubyid_t'>t</span><span class='period'>.</span><span class='id identifier rubyid_stats_options'>stats_options</span> <span class='op'>=</span> <span class='lbracket'>[</span><span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>--list-undoc</span><span class='tstring_end'>'</span></span><span class='rbracket'>]</span> <span class='comment'># optional
</span><span class='kw'>end</span>
</code></pre>
<p>All the settings: <code>files</code>, <code>options</code> and <code>stats_options</code> are optional. <code>files</code> will default to
<code>lib/**/*.rb</code>, <code>options</code> will represents any options you might want
to add and <code>stats_options</code> will pass extra options to the stats command.
Again, a full list of options is available by typing <code>yardoc --help</code>
in a shell. You can also override the options at the Rake command-line with the
OPTS environment variable:</p>
<pre class="code sh"><code class="sh">$ rake yard OPTS='--any --extra --opts'
</code></pre>
<p><strong>3. <code>yri</code> RI Implementation</strong></p>
<p>The yri binary will use the cached .yardoc database to give you quick ri-style
access to your documentation. It's way faster than ri but currently does not
work with the stdlib or core Ruby libraries, only the active project. Example:</p>
<pre class="code sh"><code class="sh">$ yri YARD::Handlers::Base#register
$ yri File.relative_path
</code></pre>
<p>Note that class methods must not be referred to with the "::" namespace
separator. Only modules, classes and constants should use "::".</p>
<p>You can also do lookups on any installed gems. Just make sure to build the
.yardoc databases for installed gems with:</p>
<pre class="code sh"><code class="sh">$ yard gems
</code></pre>
<p>If you don't have sudo access, it will write these files to your <code>~/.yard</code>
directory. <code>yri</code> will also cache lookups there.</p>
<p><strong>4. <code>yard server</code> Documentation Server</strong></p>
<p>The <code>yard server</code> command serves documentation for a local project or all installed
RubyGems. To serve documentation for a project you are working on, simply run:</p>
<pre class="code sh"><code class="sh">$ yard server
</code></pre>
<p>And the project inside the current directory will be parsed (if the source has
not yet been scanned by YARD) and served at <a href="http://localhost:8808">http://localhost:8808</a>.</p>
<h3>Live Reloading</h3>
<p>If you want to serve documentation on a project while you document it so that
you can preview the results, simply pass <code>--reload</code> (<code>-r</code>) to the above command
and YARD will reload any changed files on each request. This will allow you to
change any documentation in the source and refresh to see the new contents.</p>
<h3>Serving Gems</h3>
<p>To serve documentation for all installed gems, call:</p>
<pre class="code sh"><code class="sh">$ yard server --gems
</code></pre>
<p>This will also automatically build documentation for any gems that have not
been previously scanned. Note that in this case there will be a slight delay
between the first request of a newly parsed gem.</p>
<p><strong>5. <code>yard graph</code> Graphviz Generator</strong></p>
<p>You can use <code>yard graph</code> to generate dot graphs of your code. This, of course,
requires <a href="http://www.graphviz.org">Graphviz</a> and the <code>dot</code> binary. By default
this will generate a graph of the classes and modules in the best UML2 notation
that Graphviz can support, but without any methods listed. With the <code>--full</code>
option, methods and attributes will be listed. There is also a <code>--dependencies</code>
option to show mixin inclusions. You can output to stdout or a file, or pipe directly
to <code>dot</code>. The same public, protected and private visibility rules apply to <code>yard graph</code>.
More options can be seen by typing <code>yard graph --help</code>, but here is an example:</p>
<pre class="code sh"><code class="sh">$ yard graph --protected --full --dependencies
</code></pre>
<h2>Changelog</h2>
<p>See <a href="file.CHANGELOG.html" title="CHANGELOG">CHANGELOG</a> for a list of changes.</p>
<h2>License</h2>
<p>YARD © 2007-2016 by <a href="mailto:lsegal@soen.ca">Loren Segal</a>. YARD is
licensed under the MIT license except for some files which come from the
RDoc/Ruby distributions. Please see the <a href="file.LICENSE.html" title="LICENSE">LICENSE</a> and <a href="file.LEGAL.html" title="LEGAL">LEGAL</a>
documents for more information.</p>
</div></div>
<div id="footer">
Generated by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.12 (ruby-2.5.1).
</div>
</div>
</body>
</html>
|