yard 0.9.18 → 0.9.23

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+This document provides community guidelines for a safe, respectful, productive,
+and collaborative place for any person who is willing to contribute to the YARD
+project. It applies to all “collaborative space”, which is defined as community
+communications channels (such as mailing lists, submitted patches, commit
+comments, etc.).
+
+* Participants will be tolerant of opposing views.
+
+* Participants must ensure that their language and actions are free of personal
+  attacks and disparaging personal remarks.
+
+* When interpreting the words and actions of others, participants should always
+  assume good intentions.
+
+* Behaviour which can be reasonably considered harassment will not be tolerated.

data/CONTRIBUTING.md

@@ -0,0 +1,140 @@
+# Contributing Guide
+
+## Help YARD Help You!
+
+**YARD thrives off of the contributions of its users**. This project will gladly
+review pull requests and issues. This document outlines how to maximize
+the chance of a reported issue being resolved or pull request being accepted.
+
+## Code of Conduct
+
+**All reported issues, pull requests, communication, and code related to YARD**
+**must follow the [Code of Conduct][code] or they will be moderated immediately**.
+Please take time to familiarize yourself with the Code of Conduct before
+you get started. Fundamentally, **you are expected to behave with respect** to all
+other users.
+
+## Filing a Bug Report
+
+**You can submit bug reports on our [GitHub issue tracker][issues]**.
+
+If you believe you have found a bug, please include a few things in your report:
+
+1. **A minimal reproduction of the issue**. Providing a huge blob of code is
+   better than nothing, but providing the shortest possible set of instructions
+   is even better. Take out any instructions or code that, when removed, have
+   no effect on the problematic behavior. The easier your bug is to triage and
+   diagnose, the higher up in the priority list it will go. We can do this stuff,
+   but limited time means this may not happen immediately. Make your bug report
+   extremely accessible and you will almost guarantee a quick fix.
+
+2. **Your environment and relevant versions**. Please include your Ruby,
+   YARD, and system versions (including OS) when reporting a bug. This
+   makes it easier to diagnose problems. If the issue or stack trace
+   includes another library, consider also listing any dependencies
+   that may be affecting the issue. This is where a minimal reproduction
+   case helps a lot.
+
+3. **Your expected result**. Tell us what you think should happen. This
+   helps us to understand the context of your problem. Many complex features
+   can contain ambiguous usage, and your use case may differ from the
+   intended one. If we know your expectations, we can more easily determine
+   if the behavior is intentional or not.
+
+Finally, please **DO NOT** submit a report that states a feature simply
+*"does not work"* without any additional information in the report. Consider
+the issue from the maintainer's perspective: in order to fix your bug, we
+need to drill down to the broken line of code, and in order to do this,
+we must be able to reproduce the issue on our end to find that line of
+code. The easier we can do this, the quicker your bug gets fixed. Help
+us help you by providing as much information as you possibly can. We may
+not have the tools or environment to properly diagnose your issue, so
+your help may be required to debug the issue.
+
+Also **consider opening a pull request** to fix the issue yourself if you can.
+This will likely speed up the fix time significantly. See below for
+information on how to do this.
+
+## Asking a Question
+
+**Questions are accepted on [GitHub issues][issues], but consider signing up**
+**for the [YARD mailing list][ml]** and asking it there so that we can organize
+issues appropriately. You can also hop onto IRC (irc.freenode.net / #yard)
+for quick questions.
+
+## Asking for a Feature
+
+**YARD does not currently accept feature requests filed as GitHub issues**. If
+you are looking to have a feature implemented into YARD, consider doing this
+yourself and [submitting a pull request][pr] (PR) with your work. If the work
+required is involved, consider starting a discussion on the [mailing list][ml]
+or opening an issue to ask a question; we will be happy to have a conversation
+and let you know if the feature would be considered. They usually are, but
+it might be prudent to ask first!
+
+Please do not fret if your feature request gets closed immediately. We do this
+to keep our issue tracker clean. **Closing an issue does not mean it would not**
+**be accepted as a pull request**. If the feature would not be accepted as a
+PR, this will be communicated in the closed issue.
+
+## Making a Change via Pull Request
+
+**You can also submit pull requests on our [GitHub issue tracker][issues]**.
+
+If you've been working on a patch or feature that you want in YARD, here are
+some tips to ensure the quickest turnaround time on getting it merged in:
+
+1. **Keep your changes small**. If your feature is large, consider splitting
+   it up into smaller portions and submit pull requests for each component
+   individually. Feel free to describe this in your first PR or on the
+   mailing list, but note that it will be much easier to review changes
+   if they affect smaller portions of code at a time.
+
+2. **Keep commits brief and clean**: YARD uses Git and tries to maintain a
+   clean repository. Please ensure that you use [commit conventions][commit]
+   to make things nice and neat both in the description and commit history.
+   Specifically, consider squashing commits if you have partial or complete
+   reverts of code. Each commit should provide an atomic change that moves
+   the project forwards, not back. Any changes that only fix other parts of
+   your PR should be hidden from the commit history.
+
+3. **Follow our coding conventions**. YARD uses typical Ruby source formatting,
+   though it occasionally has minor differences with other projects you may
+   have seen. Please look through a few files (at least the file you are
+   editing) to ensure that you are consistent in the formatting your PR is
+   using.
+
+4. **Make sure you have tests**. Not all changes require tests, but if your
+   changes involve code, you should consider adding at least one new test
+   case for your change (and ideally a couple of tests). This will add
+   confidence when reviewing and will make accepting the change much easier.
+
+5. **Make sure ALL the tests pass**. YARD has a fairly large suite of tests.
+   Please make sure you can run all of the tests (`bundle exec rake`) prior
+   to submitting your PR. Please also remember that YARD supports a number
+   of environments, including OS X, Linux, Windows, and a number of older
+   Ruby versions (1.8+), so if you can test under these environments, that
+   helps (but is not required). At the very least, be aware of this fact
+   when submitting code.
+
+If your change is large, consider starting a discussion on the [mailing list][ml]
+or opening an issue to ask a question; we will be happy to have a conversation
+and let you know if the feature would be considered. They usually are, but
+it might be prudent to ask first!
+
+## Maintainers
+
+**Interested in helping to maintain YARD? Email [lsegal@soen.ca][mail]** for more
+information. Offering to be a project maintainer is an important contribution
+to open source software, and your work will be highly valued in the community.
+If you have been a contributor, consider being a member of the core team to
+help handle day-to-day operations, such as releases, bug fixes, and triage.
+You can do some of this as a non-maintainer too, but if you like this project,
+we can always use more hands on deck!
+
+[code]: https://github.com/lsegal/yard/blob/master/CODE_OF_CONDUCT.md
+[issues]: http://github.com/lsegal/yard/issues
+[commit]: http://chris.beams.io/posts/git-commit/
+[pr]: https://help.github.com/articles/using-pull-requests/
+[ml]: https://groups.google.com/forum/#!forum/yardoc
+[mail]: mailto:lsegal@soen.ca

data/Dockerfile.samus

@@ -0,0 +1,28 @@
+FROM lsegal/samus:latest as samus
+
+FROM ruby:2
+ARG VERSION
+ENV VERSION=${VERSION}
+WORKDIR /github/lsegal/yard
+ENTRYPOINT samus publish release-v${VERSION}.tar.gz
+
+# Prepare credential config
+RUN mkdir -p ~/.ssh
+RUN echo "Host *" > ~/.ssh/config
+RUN echo "    StrictHostKeyChecking no" >> ~/.ssh/config
+RUN chmod 400 ~/.ssh/config
+COPY ./.samusprep/.samus /root/.samus
+COPY ./.samusprep/.gitconfig /root/.gitconfig
+
+# Setup Samus
+ENV PATH=$PATH:/samus/bin
+COPY --from=samus /samus /samus
+
+# Install gems
+ENV BUNDLE_PATH=/var/gems
+COPY Gemfile /github/lsegal/yard
+RUN bundle
+
+# Run build
+COPY . /github/lsegal/yard
+RUN samus build --skip-restore ${VERSION}

data/Gemfile

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+
+group :development do
+  gem 'rspec'
+  gem 'rake'
+  gem 'rdoc'
+  gem 'json'
+  gem 'simplecov'
+  gem 'samus', '~> 3.0.8', :require => false
+  gem 'coveralls', :require => false
+end
+
+group :asciidoc do
+  gem 'asciidoctor'
+end
+
+group :markdown do
+  gem 'redcarpet', :platforms => [:ruby]
+end
+
+group :textile do
+  gem 'RedCloth', :platforms => [:ruby]
+end
+
+group :server do
+  gem 'rack'
+end
+
+group :i18n do
+  gem 'gettext'
+end

data/LEGAL

@@ -1,66 +1,66 @@
-LEGAL NOTICE INFORMATION
-------------------------
-
-All the files in this distribution are covered under either the MIT
-license (see the file LICENSE) except some files mentioned below.
-
-lib/parser/ruby/legacy/ruby_lex.rb:
-
-  This file is under the Ruby license. YARD uses a modified version of it.
-
-    Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
-    You can redistribute it and/or modify it under either the terms of the GPL
-    version 2 (see the file GPL), or the conditions below:
-
-      1. You may make and give away verbatim copies of the source form of the
-         software without restriction, provided that you duplicate all of the
-         original copyright notices and associated disclaimers.
-
-      2. You may modify your copy of the software in any way, provided that
-         you do at least ONE of the following:
-
-           a) place your modifications in the Public Domain or otherwise
-              make them Freely Available, such as by posting said
-          modifications to Usenet or an equivalent medium, or by allowing
-          the author to include your modifications in the software.
-
-           b) use the modified software only within your corporation or
-              organization.
-
-           c) give non-standard binaries non-standard names, with
-              instructions on where to get the original software distribution.
-
-           d) make other distribution arrangements with the author.
-
-      3. You may distribute the software in object code or binary form,
-         provided that you do at least ONE of the following:
-
-           a) distribute the binaries and library files of the software,
-          together with instructions (in the manual page or equivalent)
-          on where to get the original distribution.
-
-           b) accompany the distribution with the machine-readable source of
-          the software.
-
-           c) give non-standard binaries non-standard names, with
-              instructions on where to get the original software distribution.
-
-           d) make other distribution arrangements with the author.
-
-      4. You may modify and include the part of the software into any other
-         software (possibly commercial).  But some files in the distribution
-         are not written by the author, so that they are not under these terms.
-
-         For the list of those files and their copying conditions, see the
-         file LEGAL.
-
-      5. The scripts and library files supplied as input to or produced as
-         output from the software do not automatically fall under the
-         copyright of the software, but belong to whomever generated them,
-         and may be sold commercially, and may be aggregated with this
-         software.
-
-      6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
-         IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-         PURPOSE.
+LEGAL NOTICE INFORMATION
+------------------------
+
+All the files in this distribution are covered under either the MIT
+license (see the file LICENSE) except some files mentioned below.
+
+lib/parser/ruby/legacy/ruby_lex.rb:
+
+  This file is under the Ruby license. YARD uses a modified version of it.
+
+    Ruby is copyrighted free software by Yukihiro Matsumoto <matz@netlab.jp>.
+    You can redistribute it and/or modify it under either the terms of the GPL
+    version 2 (see the file GPL), or the conditions below:
+
+      1. You may make and give away verbatim copies of the source form of the
+         software without restriction, provided that you duplicate all of the
+         original copyright notices and associated disclaimers.
+
+      2. You may modify your copy of the software in any way, provided that
+         you do at least ONE of the following:
+
+           a) place your modifications in the Public Domain or otherwise
+              make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+           b) use the modified software only within your corporation or
+              organization.
+
+           c) give non-standard binaries non-standard names, with
+              instructions on where to get the original software distribution.
+
+           d) make other distribution arrangements with the author.
+
+      3. You may distribute the software in object code or binary form,
+         provided that you do at least ONE of the following:
+
+           a) distribute the binaries and library files of the software,
+          together with instructions (in the manual page or equivalent)
+          on where to get the original distribution.
+
+           b) accompany the distribution with the machine-readable source of
+          the software.
+
+           c) give non-standard binaries non-standard names, with
+              instructions on where to get the original software distribution.
+
+           d) make other distribution arrangements with the author.
+
+      4. You may modify and include the part of the software into any other
+         software (possibly commercial).  But some files in the distribution
+         are not written by the author, so that they are not under these terms.
+
+         For the list of those files and their copying conditions, see the
+         file LEGAL.
+
+      5. The scripts and library files supplied as input to or produced as
+         output from the software do not automatically fall under the
+         copyright of the software, but belong to whomever generated them,
+         and may be sold commercially, and may be aggregated with this
+         software.
+
+      6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+         IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+         WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+         PURPOSE.

data/LICENSE

@@ -1,22 +1,22 @@
-Copyright (c) 2007-2018 Loren Segal
-
-Permission is hereby granted, free of charge, to any person
-obtaining a copy of this software and associated documentation
-files (the "Software"), to deal in the Software without
-restriction, including without limitation the rights to use,
-copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the
-Software is furnished to do so, subject to the following
-conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
+Copyright (c) 2007-2018 Loren Segal
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,328 +1,330 @@
-# YARD: Yay! A Ruby Documentation Tool
-
-[![Homepage](http://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
-[![GitHub](http://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
-[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
-
-[![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
-[![Build Status](https://travis-ci.org/lsegal/yard.svg?branch=master)](https://travis-ci.org/lsegal/yard)
-[![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
-[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
-
-## Synopsis
-
-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.
-
-
-## Feature List
-
-**1. RDoc/SimpleMarkup Formatting Compatibility**: 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.
-
-**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:
-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 {file:docs/Tags.md#taglist Tags.md} file.
-
-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:
-
-```ruby
-# Reverses the contents of a String or IO object.
-#
-# @param contents [String, #read] the contents to reverse
-# @return [String] the contents reversed lexically
-def reverse(contents)
-  contents = contents.read if contents.respond_to? :read
-  contents.reverse
-end
-```
-
-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.
-
-**3. Custom Constructs and Extensibility of YARD**: YARD is designed to be
-extended and customized by plugins. Take for instance the scenario where you
-need to document the following code:
-
-```ruby
-class List
- # Sets the publisher name for the list.
- cattr_accessor :publisher
-end
-```
-
-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 `cattr_accessor` 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.
-
-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.
-
-**4. Raw Data Output**: 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.
-
-**5. Local Documentation Server**: YARD can serve documentation for projects
-or installed gems (similar to `gem server`) 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.
-
-
-## Installing
-
-To install YARD, use the following command:
-
-```sh
-$ gem install yard
-```
-
-(Add `sudo` if you're installing under a POSIX system as root)
-
-Alternatively, if you've checked the source out directly, you can call
-`rake install` from the root project directory.
-
-**Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
-install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
-If running `which rdoc` turns up empty, install RDoc by issuing:
-
-```sh
-$ sudo apt-get install rdoc
-```
-
-
-## Usage
-
-There are a couple of ways to use YARD. The first is via command-line, and the
-second is the Rake task.
-
-**1. yard Command-line Tool**
-
-YARD comes packaged with a executable named `yard` 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:
-
-```sh
-$ yard --help
-```
-
-Plugins can also add commands to the `yard` executable to provide extra
-functionality.
-
-### Generating Documentation
-
-<span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
-
-The most common command you will probably use is `yard doc`, or `yardoc`. You
-can type `yardoc --help` to see the options that YARD provides, but the
-easiest way to generate docs for your code is to simply type `yardoc` in your
-project root. This will assume your files are
-located in the `lib/` directory. If they are located elsewhere, you can specify
-paths and globs from the commandline via:
-
-```sh
-$ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
-```
-
-The tool will generate a `.yardoc` 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 `--use-cache` (or -c)
-option to speed up the generation process by skipping source parsing.
-
-YARD will by default only document code in your public visibility. You can
-document your protected and private code by adding `--protected` or
-`--private` to the option switches. In addition, you can add `--no-private`
-to also ignore any object that has the `@private` 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).
-
-You can also add extra informative files (README, LICENSE) by separating
-the globs and the filenames with '-'.
-
-```sh
-$ yardoc 'app/**/*.rb' - README LICENSE FAQ
-```
-
-If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is
-used:
-
-```sh
-$ yardoc - README LICENSE FAQ
-```
-
-Note that the README file can be specified with its own `--readme` switch.
-
-You can also add a `.yardopts` 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 `.yardopts` file can be found in
-{YARD::CLI::Yardoc}.
-
-### Queries
-
-The `yardoc` tool also supports a `--query` 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:
-
-```sh
---query '@api.text == "public"'
---query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
---query 'has_tag?(:api) && tag(:api).text == "public"'
-```
-
-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".
-
-Multiple `--query` arguments are allowed in the command line parameters. The
-following two lines both check for the existence of a return and param tag:
-
-```sh
---query '@return' --query '@param'
---query '@return && @param'
-```
-
-For more information about the query syntax, see the {YARD::Verifier} class.
-
-**2. Rake Task**
-
-The second most obvious is to generate docs via a Rake task. You can do this by
-adding the following to your `Rakefile`:
-
-```ruby
-YARD::Rake::YardocTask.new do |t|
- t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
- t.options = ['--any', '--extra', '--opts'] # optional
- t.stats_options = ['--list-undoc']         # optional
-end
-```
-
-All the settings: `files`, `options` and `stats_options` are optional. `files` will default to
-`lib/**/*.rb`, `options` will represents any options you might want
-to add and `stats_options` will pass extra options to the stats command.
-Again, a full list of options is available by typing `yardoc --help`
-in a shell. You can also override the options at the Rake command-line with the
-OPTS environment variable:
-
-```sh
-$ rake yard OPTS='--any --extra --opts'
-```
-
-**3. `yri` RI Implementation**
-
-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:
-
-```sh
-$ yri YARD::Handlers::Base#register
-$ yri File.relative_path
-```
-
-Note that class methods must not be referred to with the "::" namespace
-separator. Only modules, classes and constants should use "::".
-
-You can also do lookups on any installed gems. Just make sure to build the
-.yardoc databases for installed gems with:
-
-```sh
-$ yard gems
-```
-
-If you don't have sudo access, it will write these files to your `~/.yard`
-directory. `yri` will also cache lookups there.
-
-**4. `yard server` Documentation Server**
-
-The `yard server` command serves documentation for a local project or all installed
-RubyGems. To serve documentation for a project you are working on, simply run:
-
-```sh
-$ yard server
-```
-
-And the project inside the current directory will be parsed (if the source has
-not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
-
-### Live Reloading
-
-If you want to serve documentation on a project while you document it so that
-you can preview the results, simply pass `--reload` (`-r`) 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.
-
-### Serving Gems
-
-To serve documentation for all installed gems, call:
-
-```sh
-$ yard server --gems
-```
-
-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.
-
-
-**5. `yard graph` Graphviz Generator**
-
-You can use `yard graph` to generate dot graphs of your code. This, of course,
-requires [Graphviz](http://www.graphviz.org) and the `dot` 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 `--full`
-option, methods and attributes will be listed. There is also a `--dependencies`
-option to show mixin inclusions. You can output to stdout or a file, or pipe directly
-to `dot`. The same public, protected and private visibility rules apply to `yard graph`.
-More options can be seen by typing `yard graph --help`, but here is an example:
-
-```sh
-$ yard graph --protected --full --dependencies
-```
-
-
-## Changelog
-
-See {file:CHANGELOG.md} for a list of changes.
-
-## License
-
-YARD &copy; 2007-2018 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
-licensed under the MIT license except for some files which come from the
-RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
-documents for more information.
+# YARD: Yay! A Ruby Documentation Tool
+
+[![Homepage](http://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
+[![GitHub](http://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
+
+[![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
+[![Build Status](https://travis-ci.org/lsegal/yard.svg?branch=master)](https://travis-ci.org/lsegal/yard)
+[![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
+[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
+
+## Synopsis
+
+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.
+
+
+## Feature List
+
+**1. RDoc/SimpleMarkup Formatting Compatibility**: 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.
+
+**2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:
+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 {file:docs/Tags.md#taglist Tags.md} file.
+
+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:
+
+```ruby
+# Reverses the contents of a String or IO object.
+#
+# @param contents [String, #read] the contents to reverse
+# @return [String] the contents reversed lexically
+def reverse(contents)
+  contents = contents.read if contents.respond_to? :read
+  contents.reverse
+end
+```
+
+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.
+
+**3. Custom Constructs and Extensibility of YARD**: YARD is designed to be
+extended and customized by plugins. Take for instance the scenario where you
+need to document the following code:
+
+```ruby
+class List
+ # Sets the publisher name for the list.
+ cattr_accessor :publisher
+end
+```
+
+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 `cattr_accessor` 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.
+
+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.
+
+**4. Raw Data Output**: 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.
+
+**5. Local Documentation Server**: YARD can serve documentation for projects
+or installed gems (similar to `gem server`) 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.
+
+
+## Installing
+
+To install YARD, use the following command:
+
+```sh
+$ gem install yard
+```
+
+(Add `sudo` if you're installing under a POSIX system as root)
+
+Alternatively, if you've checked the source out directly, you can call
+`rake install` from the root project directory.
+
+**Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
+install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
+If running `which rdoc` turns up empty, install RDoc by issuing:
+
+```sh
+$ sudo apt-get install rdoc
+```
+
+
+## Usage
+
+There are a couple of ways to use YARD. The first is via command-line, and the
+second is the Rake task.
+
+**1. yard Command-line Tool**
+
+YARD comes packaged with a executable named `yard` 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:
+
+```sh
+$ yard --help
+```
+
+Plugins can also add commands to the `yard` executable to provide extra
+functionality.
+
+### Generating Documentation
+
+<span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
+
+The most common command you will probably use is `yard doc`, or `yardoc`. You
+can type `yardoc --help` to see the options that YARD provides, but the
+easiest way to generate docs for your code is to simply type `yardoc` in your
+project root. This will assume your files are
+located in the `lib/` directory. If they are located elsewhere, you can specify
+paths and globs from the commandline via:
+
+```sh
+$ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
+```
+
+The tool will generate a `.yardoc` 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 `--use-cache` (or -c)
+option to speed up the generation process by skipping source parsing.
+
+YARD will by default only document code in your public visibility. You can
+document your protected and private code by adding `--protected` or
+`--private` to the option switches. In addition, you can add `--no-private`
+to also ignore any object that has the `@private` 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).
+
+You can also add extra informative files (README, LICENSE) by separating
+the globs and the filenames with '-'.
+
+```sh
+$ yardoc 'app/**/*.rb' - README LICENSE FAQ
+```
+
+If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is
+used:
+
+```sh
+$ yardoc - README LICENSE FAQ
+```
+
+Note that the README file can be specified with its own `--readme` switch.
+
+You can also add a `.yardopts` 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 `.yardopts` file can be found in
+{YARD::CLI::Yardoc}.
+
+### Queries
+
+The `yardoc` tool also supports a `--query` 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:
+
+```sh
+--query '@api.text == "public"'
+--query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
+--query 'has_tag?(:api) && tag(:api).text == "public"'
+```
+
+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".
+
+Multiple `--query` arguments are allowed in the command line parameters. The
+following two lines both check for the existence of a return and param tag:
+
+```sh
+--query '@return' --query '@param'
+--query '@return && @param'
+```
+
+For more information about the query syntax, see the {YARD::Verifier} class.
+
+**2. Rake Task**
+
+The second most obvious is to generate docs via a Rake task. You can do this by
+adding the following to your `Rakefile`:
+
+```ruby
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+ t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+ t.options = ['--any', '--extra', '--opts'] # optional
+ t.stats_options = ['--list-undoc']         # optional
+end
+```
+
+All the settings: `files`, `options` and `stats_options` are optional. `files` will default to
+`lib/**/*.rb`, `options` will represents any options you might want
+to add and `stats_options` will pass extra options to the stats command.
+Again, a full list of options is available by typing `yardoc --help`
+in a shell. You can also override the options at the Rake command-line with the
+OPTS environment variable:
+
+```sh
+$ rake yard OPTS='--any --extra --opts'
+```
+
+**3. `yri` RI Implementation**
+
+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:
+
+```sh
+$ yri YARD::Handlers::Base#register
+$ yri File.relative_path
+```
+
+Note that class methods must not be referred to with the "::" namespace
+separator. Only modules, classes and constants should use "::".
+
+You can also do lookups on any installed gems. Just make sure to build the
+.yardoc databases for installed gems with:
+
+```sh
+$ yard gems
+```
+
+If you don't have sudo access, it will write these files to your `~/.yard`
+directory. `yri` will also cache lookups there.
+
+**4. `yard server` Documentation Server**
+
+The `yard server` command serves documentation for a local project or all installed
+RubyGems. To serve documentation for a project you are working on, simply run:
+
+```sh
+$ yard server
+```
+
+And the project inside the current directory will be parsed (if the source has
+not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
+
+### Live Reloading
+
+If you want to serve documentation on a project while you document it so that
+you can preview the results, simply pass `--reload` (`-r`) 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.
+
+### Serving Gems
+
+To serve documentation for all installed gems, call:
+
+```sh
+$ yard server --gems
+```
+
+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.
+
+
+**5. `yard graph` Graphviz Generator**
+
+You can use `yard graph` to generate dot graphs of your code. This, of course,
+requires [Graphviz](http://www.graphviz.org) and the `dot` 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 `--full`
+option, methods and attributes will be listed. There is also a `--dependencies`
+option to show mixin inclusions. You can output to stdout or a file, or pipe directly
+to `dot`. The same public, protected and private visibility rules apply to `yard graph`.
+More options can be seen by typing `yard graph --help`, but here is an example:
+
+```sh
+$ yard graph --protected --full --dependencies
+```
+
+
+## Changelog
+
+See {file:CHANGELOG.md} for a list of changes.
+
+## License
+
+YARD &copy; 2007-2018 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
+licensed under the MIT license except for some files which come from the
+RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
+documents for more information.