Permalink
Browse files

The great whitespace fix of 2012

  • Loading branch information...
1 parent a463828 commit fa147d95099d004fe377d7dec70dbaf98a0ed61b @lsegal committed Apr 30, 2012
Showing with 3,244 additions and 3,246 deletions.
  1. +5 −5 LEGAL
  2. +52 −52 README.md
  3. +5 −5 Rakefile
  4. +1 −1 benchmarks/builtins_vs_eval.rb
  5. +4 −4 benchmarks/erb_vs_erubis.rb
  6. +5 −5 benchmarks/generation.rb
  7. +2 −2 benchmarks/parsing.rb
  8. +4 −4 benchmarks/registry_store_types.rb
  9. +10 −10 docs/CodeObjects.md
  10. +21 −21 docs/Handlers.md
  11. +7 −7 docs/Overview.md
  12. +30 −30 docs/Parser.md
  13. +4 −4 docs/Tags.md
  14. +58 −58 docs/Templates.md
  15. +133 −133 docs/WhatsNew.md
  16. +1 −1 docs/templates/default/yard_tags/html/list.erb
  17. +1 −1 lib/yard/cli/diff.rb
  18. +1 −1 lib/yard/cli/list.rb
  19. +2 −2 lib/yard/cli/server.rb
  20. +1 −1 lib/yard/cli/stats.rb
  21. +1 −1 lib/yard/cli/yardoc.rb
  22. +2 −2 lib/yard/cli/yri.rb
  23. +3 −3 lib/yard/code_objects/base.rb
  24. +1 −1 lib/yard/code_objects/extra_file_object.rb
  25. +21 −21 lib/yard/code_objects/macro_object.rb
  26. +1 −1 lib/yard/code_objects/method_object.rb
  27. +8 −8 lib/yard/config.rb
  28. +9 −9 lib/yard/docstring.rb
  29. +4 −4 lib/yard/docstring_parser.rb
  30. +18 −18 lib/yard/handlers/base.rb
  31. +1 −1 lib/yard/handlers/c/alias_handler.rb
  32. +2 −2 lib/yard/handlers/c/attribute_handler.rb
  33. +15 −15 lib/yard/handlers/c/base.rb
  34. +2 −2 lib/yard/handlers/c/class_handler.rb
  35. +1 −1 lib/yard/handlers/c/constant_handler.rb
  36. +9 −9 lib/yard/handlers/c/handler_methods.rb
  37. +1 −1 lib/yard/handlers/c/init_handler.rb
  38. +2 −2 lib/yard/handlers/c/method_handler.rb
  39. +1 −1 lib/yard/handlers/c/mixin_handler.rb
  40. +1 −1 lib/yard/handlers/c/module_handler.rb
  41. +1 −1 lib/yard/handlers/c/override_comment_handler.rb
  42. +1 −1 lib/yard/handlers/c/path_handler.rb
  43. +1 −1 lib/yard/handlers/c/struct_handler.rb
  44. +9 −9 lib/yard/handlers/processor.rb
  45. +1 −1 lib/yard/handlers/ruby/attribute_handler.rb
  46. +1 −1 lib/yard/handlers/ruby/base.rb
  47. +1 −1 lib/yard/handlers/ruby/legacy/attribute_handler.rb
  48. +3 −3 lib/yard/handlers/ruby/legacy/base.rb
  49. +2 −2 lib/yard/logging.rb
  50. +25 −25 lib/yard/options.rb
  51. +2 −2 lib/yard/parser/c/c_parser.rb
  52. +3 −3 lib/yard/parser/c/comment_parser.rb
  53. +8 −8 lib/yard/parser/c/statement.rb
  54. +1 −1 lib/yard/parser/ruby/ast_node.rb
  55. +1 −1 lib/yard/parser/ruby/legacy/statement_list.rb
  56. +6 −6 lib/yard/parser/ruby/ruby_parser.rb
  57. +53 −53 lib/yard/parser/source_parser.rb
  58. +1 −1 lib/yard/rake/yardoc_task.rb
  59. +3 −3 lib/yard/serializers/file_system_serializer.rb
  60. +1 −1 lib/yard/server/commands/search_command.rb
  61. +1 −1 lib/yard/server/rack_adapter.rb
  62. +1 −1 lib/yard/server/templates/default/fulldoc/html/css/custom.css
  63. +1 −1 lib/yard/tags/default_factory.rb
  64. +5 −5 lib/yard/tags/directives.rb
  65. +3 −3 lib/yard/tags/library.rb
  66. +1 −1 lib/yard/templates/helpers/base_helper.rb
  67. +4 −4 lib/yard/templates/helpers/html_helper.rb
  68. +1 −1 lib/yard/templates/helpers/markup/rdoc_markup.rb
  69. +8 −8 lib/yard/templates/template.rb
  70. +12 −12 lib/yard/templates/template_options.rb
  71. +4 −4 spec/cli/command_parser_spec.rb
  72. +3 −3 spec/cli/command_spec.rb
  73. +13 −13 spec/cli/config_spec.rb
  74. +8 −8 spec/cli/diff_spec.rb
  75. +12 −12 spec/cli/gems_spec.rb
  76. +2 −2 spec/cli/help_spec.rb
  77. +23 −23 spec/cli/server_spec.rb
  78. +11 −11 spec/cli/stats_spec.rb
  79. +59 −59 spec/cli/yardoc_spec.rb
  80. +8 −8 spec/cli/yri_spec.rb
  81. +46 −46 spec/code_objects/base_spec.rb
  82. +33 −33 spec/code_objects/class_object_spec.rb
  83. +5 −5 spec/code_objects/code_object_list_spec.rb
  84. +3 −3 spec/code_objects/constants_spec.rb
  85. +19 −19 spec/code_objects/extra_file_object_spec.rb
  86. +20 −20 spec/code_objects/macro_object_spec.rb
  87. +22 −22 spec/code_objects/method_object_spec.rb
  88. +16 −16 spec/code_objects/module_object_spec.rb
  89. +6 −6 spec/code_objects/namespace_object_spec.rb
  90. +19 −19 spec/code_objects/proxy_spec.rb
  91. +21 −21 spec/config_spec.rb
  92. +1 −1 spec/core_ext/array_spec.rb
  93. +8 −8 spec/core_ext/file_spec.rb
  94. +1 −1 spec/core_ext/hash_spec.rb
  95. +3 −3 spec/core_ext/insertion_spec.rb
  96. +1 −1 spec/core_ext/module_spec.rb
  97. +6 −6 spec/core_ext/string_spec.rb
  98. +11 −11 spec/core_ext/symbol_hash_spec.rb
  99. +34 −34 spec/docstring_spec.rb
  100. +14 −14 spec/handlers/alias_handler_spec.rb
  101. +20 −20 spec/handlers/attribute_handler_spec.rb
  102. +16 −16 spec/handlers/base_spec.rb
  103. +1 −1 spec/handlers/c/alias_handler_spec.rb
  104. +2 −2 spec/handlers/c/attribute_handler_spec.rb
  105. +7 −7 spec/handlers/c/class_handler_spec.rb
  106. +5 −5 spec/handlers/c/constant_handler_spec.rb
  107. +3 −3 spec/handlers/c/init_handler_spec.rb
  108. +14 −14 spec/handlers/c/method_handler_spec.rb
  109. +1 −1 spec/handlers/c/mixin_handler_spec.rb
  110. +4 −4 spec/handlers/c/module_handler_spec.rb
  111. +4 −4 spec/handlers/c/override_comment_handler_spec.rb
  112. +1 −1 spec/handlers/c/struct_handler_spec.rb
  113. +10 −10 spec/handlers/class_condition_handler_spec.rb
  114. +38 −38 spec/handlers/class_handler_spec.rb
  115. +1 −1 spec/handlers/class_variable_handler_spec.rb
  116. +7 −7 spec/handlers/constant_handler_spec.rb
  117. +5 −5 spec/handlers/examples/alias_handler_001.rb.txt
  118. +9 −9 spec/handlers/examples/class_condition_handler_001.rb.txt
  119. +1 −1 spec/handlers/examples/class_handler_001.rb.txt
  120. +16 −16 spec/handlers/examples/dsl_handler_001.rb.txt
  121. +14 −14 spec/handlers/examples/exception_handler_001.rb.txt
  122. +2 −2 spec/handlers/examples/method_condition_handler_001.rb.txt
  123. +12 −12 spec/handlers/examples/method_handler_001.rb.txt
  124. +4 −4 spec/handlers/examples/mixin_handler_001.rb.txt
  125. +1 −1 spec/handlers/examples/private_constant_handler_001.rb.txt
  126. +3 −3 spec/handlers/examples/visibility_handler_001.rb.txt
  127. +13 −14 spec/handlers/examples/yield_handler_001.rb.txt
  128. +9 −9 spec/handlers/exception_handler_spec.rb
  129. +2 −2 spec/handlers/extend_handler_spec.rb
  130. +34 −34 spec/handlers/legacy_base_spec.rb
  131. +2 −2 spec/handlers/method_condition_handler_spec.rb
  132. +29 −29 spec/handlers/method_handler_spec.rb
  133. +9 −9 spec/handlers/mixin_handler_spec.rb
  134. +4 −4 spec/handlers/module_function_handler_spec.rb
  135. +6 −6 spec/handlers/module_handler_spec.rb
  136. +3 −3 spec/handlers/private_constant_handler_spec.rb
  137. +4 −4 spec/handlers/processor_spec.rb
  138. +1 −2 spec/handlers/spec_helper.rb
  139. +6 −6 spec/handlers/visibility_handler_spec.rb
  140. +8 −8 spec/handlers/yield_handler_spec.rb
  141. +19 −19 spec/options_spec.rb
  142. +3 −3 spec/parser/base_spec.rb
  143. +7 −7 spec/parser/c_parser_spec.rb
  144. +187 −187 spec/parser/examples/array.c.txt
  145. +1 −1 spec/parser/examples/extrafile.c.txt
  146. +1 −1 spec/parser/examples/override.c.txt
  147. +1 −1 spec/parser/ruby/ast_node_spec.rb
  148. +24 −24 spec/parser/ruby/legacy/statement_list_spec.rb
  149. +7 −7 spec/parser/ruby/legacy/token_list_spec.rb
  150. +33 −33 spec/parser/ruby/ruby_parser_spec.rb
  151. +65 −65 spec/parser/source_parser_spec.rb
  152. +4 −4 spec/parser/tag_parsing_spec.rb
  153. +8 −8 spec/rake/yardoc_task_spec.rb
  154. +38 −38 spec/registry_spec.rb
  155. +25 −25 spec/registry_store_spec.rb
  156. +12 −12 spec/serializers/file_system_serializer_spec.rb
  157. +2 −2 spec/serializers/yardoc_serializer_spec.rb
  158. +3 −3 spec/server/adapter_spec.rb
  159. +8 −8 spec/server/commands/base_spec.rb
  160. +3 −3 spec/server/commands/library_command_spec.rb
  161. +7 −7 spec/server/commands/static_file_command_spec.rb
  162. +1 −1 spec/server/doc_server_helper_spec.rb
  163. +6 −6 spec/server/doc_server_serializer_spec.rb
  164. +3 −3 spec/server/rack_adapter_spec.rb
  165. +15 −15 spec/server/router_spec.rb
  166. +4 −4 spec/server/static_caching_spec.rb
  167. +7 −7 spec/spec_helper.rb
  168. +16 −16 spec/tags/default_factory_spec.rb
  169. +3 −3 spec/tags/directives_spec.rb
  170. +4 −4 spec/tags/library_spec.rb
  171. +6 −6 spec/tags/overload_tag_spec.rb
  172. +8 −8 spec/tags/ref_tag_list_spec.rb
  173. +5 −5 spec/templates/class_spec.rb
  174. +4 −4 spec/templates/constant_spec.rb
  175. +15 −15 spec/templates/engine_spec.rb
  176. +98 −98 spec/templates/examples/class001.html
  177. +17 −17 spec/templates/examples/class002.html
  178. +1 −1 spec/templates/examples/constant001.txt
  179. +39 −39 spec/templates/examples/method001.html
  180. +22 −22 spec/templates/examples/method002.html
  181. +55 −55 spec/templates/examples/method003.html
  182. +5 −5 spec/templates/examples/method004.html
  183. +24 −24 spec/templates/examples/method005.html
  184. +298 −298 spec/templates/examples/module001.html
  185. +120 −120 spec/templates/examples/module002.html
  186. +70 −70 spec/templates/examples/module003.html
  187. +182 −182 spec/templates/examples/module004.html
  188. +29 −29 spec/templates/helpers/base_helper_spec.rb
  189. +64 −64 spec/templates/helpers/html_helper_spec.rb
  190. +4 −4 spec/templates/helpers/html_syntax_highlight_helper_spec.rb
  191. +16 −16 spec/templates/helpers/markup/rdoc_markup_spec.rb
  192. +16 −16 spec/templates/helpers/markup_helper_spec.rb
  193. +7 −7 spec/templates/helpers/method_helper_spec.rb
  194. +2 −2 spec/templates/helpers/shared_signature_examples.rb
  195. +3 −3 spec/templates/helpers/text_helper_spec.rb
  196. +11 −11 spec/templates/method_spec.rb
  197. +19 −19 spec/templates/module_spec.rb
  198. +5 −5 spec/templates/onefile_spec.rb
  199. +23 −23 spec/templates/section_spec.rb
  200. +1 −1 spec/templates/spec_helper.rb
  201. +3 −3 spec/templates/tag_spec.rb
  202. +44 −44 spec/templates/template_spec.rb
  203. +5 −5 spec/verifier_spec.rb
  204. +2 −2 templates/default/class/setup.rb
  205. +1 −1 templates/default/docstring/html/abstract.erb
  206. +1 −1 templates/default/docstring/html/note.erb
  207. +1 −1 templates/default/docstring/html/private.erb
  208. +1 −1 templates/default/docstring/html/todo.erb
  209. +2 −2 templates/default/docstring/setup.rb
  210. +2 −2 templates/default/fulldoc/html/css/full_list.css
  211. +30 −30 templates/default/fulldoc/html/css/style.css
  212. +2 −2 templates/default/fulldoc/html/full_list.erb
  213. +7 −7 templates/default/fulldoc/html/js/app.js
  214. +8 −8 templates/default/fulldoc/html/js/full_list.js
  215. +16 −16 templates/default/fulldoc/html/setup.rb
  216. +1 −1 templates/default/layout/dot/header.erb
  217. +2 −2 templates/default/layout/html/breadcrumb.erb
  218. +1 −1 templates/default/layout/html/footer.erb
  219. +3 −3 templates/default/layout/html/layout.erb
  220. +1 −1 templates/default/layout/html/objects.erb
  221. +1 −1 templates/default/layout/html/search.erb
  222. +4 −4 templates/default/layout/html/setup.rb
  223. +3 −3 templates/default/method_details/html/method_signature.erb
  224. +1 −1 templates/default/module/dot/setup.rb
  225. +1 −1 templates/default/module/html/children.erb
  226. +4 −4 templates/default/module/html/inherited_methods.erb
  227. +1 −1 templates/default/module/html/method_details_list.erb
  228. +7 −7 templates/default/module/setup.rb
  229. +1 −1 templates/default/module/text/setup.rb
  230. +1 −1 templates/default/onefile/html/layout.erb
  231. +2 −2 templates/default/onefile/html/setup.rb
  232. +9 −9 templates/guide/fulldoc/html/css/style.css
  233. +6 −6 templates/guide/fulldoc/html/js/app.js
  234. +1 −1 templates/guide/fulldoc/html/setup.rb
  235. +6 −6 templates/guide/layout/html/layout.erb
  236. +1 −1 templates/guide/layout/html/setup.rb
  237. +1 −1 templates/guide/method/html/setup.rb
  238. +1 −1 yard.gemspec
View
10 LEGAL
@@ -1,15 +1,15 @@
LEGAL NOTICE INFORMATION
------------------------
-All the files in this distribution are covered under either the MIT
+All the files in this distribution are covered under either the MIT
license (see the file LICENSE) except some files mentioned below.
lib/parser/c_parser.rb:
This file includes code from the RDoc distribution. It is under the Ruby
license but adds the following copyright:
-
- RDoc is copyrighted free software by Dave Thomas, Eric Hodel, and others.
+
+ RDoc is copyrighted free software by Dave Thomas, Eric Hodel, and others.
It is licensed under the same terms as Ruby
lib/parser/ruby/legacy/ruby_lex.rb:
@@ -62,9 +62,9 @@ lib/parser/ruby/legacy/ruby_lex.rb:
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
+ 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,
+ copyright of the software, but belong to whomever generated them,
and may be sold commercially, and may be aggregated with this
software.
View
104 README.md
@@ -23,7 +23,7 @@ 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
@@ -34,8 +34,8 @@ 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
+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.
@@ -46,32 +46,32 @@ 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:
- # Reverses the contents of a String or IO object.
- #
- # @param [String, #read] contents the contents to reverse
- # @return [String] the contents reversed lexically
- def reverse(contents)
- contents = contents.read if respond_to? :read
- contents.reverse
+ # Reverses the contents of a String or IO object.
+ #
+ # @param [String, #read] contents the contents to reverse
+ # @return [String] the contents reversed lexically
+ def reverse(contents)
+ contents = contents.read if 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
+
+**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:
-
+
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
@@ -83,7 +83,7 @@ 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
@@ -98,8 +98,8 @@ 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
+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.
@@ -109,24 +109,24 @@ Installing
To install YARD, use the following command:
$ 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
+
+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.
+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:
$ 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.
+second is the Rake task.
**1. yard Command-line Tool**
@@ -135,26 +135,26 @@ functions of YARD, including generating documentation, graphs running the
YARD server, and so on. To view a list of available YARD commands, type:
$ 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
+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:
$ 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)
+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
@@ -170,7 +170,7 @@ You can also add extra informative files (README, LICENSE) by separating
the globs and the filenames with '-'.
$ yardoc 'app/**/*.rb' - README LICENSE FAQ
-
+
If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is
used:
@@ -179,7 +179,7 @@ used:
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
+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}.
@@ -195,20 +195,20 @@ the same result:
--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.
+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:
--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
+The second most obvious is to generate docs via a Rake task. You can do this by
adding the following to your `Rakefile`:
YARD::Rake::YardocTask.new do |t|
@@ -223,7 +223,7 @@ in a shell. You can also override the options at the Rake command-line with the
OPTS environment variable:
$ 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
@@ -232,15 +232,15 @@ work with the stdlib or core Ruby libraries, only the active project. Example:
$ yri YARD::Handlers::Base#register
$ yri File.relative_path
-
-Note that class methods must not be referred to with the "::" namespace
+
+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:
$ sudo yard gems
-
+
If you don't have sudo access, it will write these files to your `~/.yard`
directory. `yri` will also cache lookups there.
@@ -250,7 +250,7 @@ The `yard server` command serves documentation for a local project or all instal
RubyGems. To serve documentation for a project you are working on, simply run:
$ 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).
@@ -266,7 +266,7 @@ change any documentation in the source and refresh to see the new contents.
To serve documentation for all installed gems, call:
$ 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.
@@ -482,33 +482,33 @@ Changelog
RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your
.gemspec file.
-- **Jun.07.09**: 0.2.3 release. See the {file:docs/WhatsNew.md} file for a
+- **Jun.07.09**: 0.2.3 release. See the {file:docs/WhatsNew.md} file for a
list of important new features.
-- **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's
+- **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's
conception and involves a complete overhaul of the parser and API to make it
more robust and far easier to extend and use for the developer.
-- **Feb.20.08**: 0.2.1 release.
+- **Feb.20.08**: 0.2.1 release.
- **Feb.24.07**: Released 0.1a experimental version for testing. The goal here is
- to get people testing YARD on their code because there are too many possible
- code styles to fit into a sane amount of test cases. It also demonstrates the
- power of YARD and what to expect from the syntax (Yardoc style meta tags).
+ to get people testing YARD on their code because there are too many possible
+ code styles to fit into a sane amount of test cases. It also demonstrates the
+ power of YARD and what to expect from the syntax (Yardoc style meta tags).
Contributors
------------
Special thanks to all contributors for submitting patches. A full list of
-contributors including their patches can be found at:
+contributors including their patches can be found at:
http://github.com/lsegal/yard/contributors
Copyright
---------
-YARD &copy; 2007-2011 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
+YARD &copy; 2007-2011 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}
+RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
documents for more information.
View
10 Rakefile
@@ -14,7 +14,7 @@ task :gem do
end
desc "Installs the gem"
-task :install => :gem do
+task :install => :gem do
sh "#{SUDO} gem install yard-#{YARD::VERSION}.gem --no-rdoc --no-ri"
end
@@ -65,9 +65,9 @@ begin
t.rspec_opts += ['-I', YARD::ROOT]
t.pattern = "spec/**/*_spec.rb"
t.verbose = $DEBUG ? true : false
-
+
if ENV['RCOV']
- t.rcov = true
+ t.rcov = true
t.rcov_opts = ['-x', hide]
end
end
@@ -76,15 +76,15 @@ rescue LoadError
begin # Try for rspec 1.x
require 'spec'
require 'spec/rake/spectask'
-
+
Spec::Rake::SpecTask.new("specs") do |t|
$DEBUG = true if ENV['DEBUG']
t.spec_opts = ["--format", "specdoc", "--colour"]
t.spec_opts += ["--require", File.join(File.dirname(__FILE__), 'spec', 'spec_helper')]
t.pattern = "spec/**/*_spec.rb"
if ENV['RCOV']
- t.rcov = true
+ t.rcov = true
t.rcov_opts = ['-x', hide]
end
end
View
2 benchmarks/builtins_vs_eval.rb
@@ -9,7 +9,7 @@ def bench_builtins(name)
def bench_eval(name)
eval(name).is_a?(Class)
-rescue
+rescue
false
end
View
8 benchmarks/erb_vs_erubis.rb
@@ -17,7 +17,7 @@ module YARD; module Templates; module Template
def erb_with(str, x) Erubis::Eruby.new(str) end
end end end
eof
-
+
rungen
end
@@ -27,7 +27,7 @@ module YARD; module Templates; module Template
def erb_with(str, x) Erubis::FastEruby.new(str) end
end end end
eof
-
+
rungen
end
@@ -37,7 +37,7 @@ module YARD; module Templates; module Template
def erb_with(str, x) Erubis::TinyEruby.new(str) end
end end end
eof
-
+
rungen
end
@@ -47,7 +47,7 @@ module YARD; module Templates; module Template
def erb_with(str, x) ERB.new(str, nil) end
end end end
eof
-
+
rungen
end
end
View
10 benchmarks/generation.rb
@@ -2,20 +2,20 @@
require File.join(File.dirname(__FILE__), '..', 'lib', 'yard')
unless YARD::CodeObjects::Proxy.private_instance_methods.include?('to_obj')
- raise "This benchmark is dependent on YARD::CodeObjects::Proxy#to_obj"
+ raise "This benchmark is dependent on YARD::CodeObjects::Proxy#to_obj"
end
def rungen
YARD::Registry.clear
- YARD::CLI::Yardoc.run('--quiet', '--use-cache')
+ YARD::CLI::Yardoc.run('--quiet', '--use-cache')
end
def redef(lock = false)
eval <<-eof
- class YARD::CodeObjects::Proxy;
+ class YARD::CodeObjects::Proxy;
def to_obj
- @obj #{lock ? '||' : ''}= YARD::Registry.resolve(@namespace, @name)
- end
+ @obj #{lock ? '||' : ''}= YARD::Registry.resolve(@namespace, @name)
+ end
end
eof
end
View
4 benchmarks/parsing.rb
@@ -15,8 +15,8 @@
]
Benchmark.bmbm do |x|
- x.report("parse in order") { YARD::Registry.clear; YARD.parse PATH_ORDER, [], Logger::ERROR }
- x.report("parse") { YARD::Registry.clear; YARD.parse 'lib/**/*.rb', [], Logger::ERROR }
+ x.report("parse in order") { YARD::Registry.clear; YARD.parse PATH_ORDER, [], Logger::ERROR }
+ x.report("parse") { YARD::Registry.clear; YARD.parse 'lib/**/*.rb', [], Logger::ERROR }
end
=begin
View
8 benchmarks/registry_store_types.rb
@@ -6,7 +6,7 @@ def parse_and_select_objects
YARD::Registry.load_all
$paths = []
4.times { $paths << YARD::Registry.paths[rand(YARD::Registry.paths.size)] }
-
+
$regular_registry = {}
$types_registry = {}
YARD::Registry.all.each do |object|
@@ -34,9 +34,9 @@ def run_lookup_with_types
__END__
# Run on March 22 2012
-["YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar#initialize",
- "YARD::Parser::C::CParser#enumerator",
- "YARD::CodeObjects::ClassObject#inherited_meths",
+["YARD::Parser::Ruby::Legacy::RubyToken::TkUnknownChar#initialize",
+ "YARD::Parser::C::CParser#enumerator",
+ "YARD::CodeObjects::ClassObject#inherited_meths",
"YARD::Parser::C::Statement#source="]
Rehearsal ----------------------------------------------
normal 0.180000 0.000000 0.180000 ( 0.182640)
View
20 docs/CodeObjects.md
@@ -14,9 +14,9 @@ and non-namespace objects. A namespace object refers to any object in Ruby that
other objects defined inside of it. In the context of Ruby, this specifically means
modules and classes (both of which are subclasses of `NamespaceObject`). These objects
act like tree structures, maintaining a list of all of their direct children. All non
-namespace objects are simply subclasses of the Base class. The {YARD::CodeObjects::RootObject RootObject}
+namespace objects are simply subclasses of the Base class. The {YARD::CodeObjects::RootObject RootObject}
is a special kind of `NamespaceObject` which refers to the top level namespace in Ruby.
-Methods that accept a namespace object as a parameter should also accept the symbol
+Methods that accept a namespace object as a parameter should also accept the symbol
`:root` as a shortcut for the root object.
The following is an overview of the classes within the `CodeObjects` namespace:
@@ -27,7 +27,7 @@ The following is an overview of the classes within the `CodeObjects` namespace:
All CodeObjects are uniquely defined by their implementation of {YARD::CodeObjects::Base#path}.
This path is used to locate or store a code object in the {YARD::Registry}. It is therefore
-essential that any Base subclass return a unique String value for #path so that the
+essential that any Base subclass return a unique String value for #path so that the
object may co-exist with other objects in the Registry.
In practice, a path is simply the conventional Ruby representation of a class,
@@ -46,7 +46,7 @@ CodeObjects classes are coupled with the {YARD::Registry} class which keeps trac
all instantiated code objects. This is an explicit design choice to allow objects
to be fetched, cached, imported and exported from a centralized location. As mentioned
above, this coupling is a result of the fact that each object is uniquely identified by
-its path, which is used to implement lookups. You can read more about the registry
+its path, which is used to implement lookups. You can read more about the registry
in the {YARD::Registry} class.
## Identity Map
@@ -57,7 +57,7 @@ allows developers to create a code object without checking if it already exists
the {YARD::Registry}. The following example will only create one object:
id = ClassObject.new(:root, "MyClass").object_id #=> 13352
- ClassObject.new(:root, "MyClass").object_id #=> 13352
+ ClassObject.new(:root, "MyClass").object_id #=> 13352
## Proxy Objects
@@ -69,8 +69,8 @@ attributes of a proxy are accessed, it will immediately be resolved to the objec
at its declared path. In the case where such an object exists, it will act as
a delegate to the object. However, if the object does not exist, a warning will
be raised. Whenever arbitrary code objects are used, care should be taken in
-order to make sure attributes are not accessed on unresolvable proxies. An
-unresolvable proxy will return a class name of `Proxy` and #type of `:proxy`,
+order to make sure attributes are not accessed on unresolvable proxies. An
+unresolvable proxy will return a class name of `Proxy` and #type of `:proxy`,
for example:
P(:InvalidObject).type == :proxy #=> true
@@ -85,8 +85,8 @@ it is possible to simply do:
object = MethodObject.new(:root, "my_method")
object[:modified_at] = Time.now
-
-This value can now be retrieved on this object both by the hash `[]` syntax as
+
+This value can now be retrieved on this object both by the hash `[]` syntax as
well as like any other method:
object.modified_at #=> 2009-06-03 20:08:46 -0400
@@ -111,5 +111,5 @@ following is an implementation of the path for a hypothetical `FooObject`:
end
Note that if our FooObject is a `NamespaceObject`, meaning if it can have child
-FooObjects defined inside of it, you may need to verify that the prefix is only
+FooObjects defined inside of it, you may need to verify that the prefix is only
applied once.
View
42 docs/Handlers.md
@@ -27,8 +27,8 @@ state about what is being processed. For instance, the processor is what keeps
track of the current namespace (the module or class an object is being defined
in), scope (class or instance), file and owner. The owner refers to the object
that is most directly responsible for the source statement being processed. This
-is most often the same as the namespace, except when parsing the body of a method,
-where the namespace would be the class/module the method is defined in and the
+is most often the same as the namespace, except when parsing the body of a method,
+where the namespace would be the class/module the method is defined in and the
owner would be the method object itself.
## Implementing a Handler
@@ -42,13 +42,13 @@ class method. A very simple handler that handles a module definition would be:
class MyModuleHandler < YARD::Handlers::Ruby::Base
handles :module
-
+
def process
puts "Handling a module named #{statement[0].source}"
end
end
-
-For details on what nodes are, and what node types are, see the
+
+For details on what nodes are, and what node types are, see the
{file:docs/Parser.md parser architecture document}.
In this case the node type being handled is the `:module` type. More than one
@@ -66,32 +66,32 @@ call can be handled by declaring the following in a `handles` statement:
class MyHandler < YARD::Handlers::Ruby::Base
handles method_call(:describe)
-
+
def process
# Process the method call
end
end
-
-In this case we handle any of the method calls to method name `describe` with
+
+In this case we handle any of the method calls to method name `describe` with
the following syntaxes:
-
+
describe(something)
describe arg1, arg2, arg3
describe(something) { perform_a_block }
describe "Something" do
a_block
end
-
+
### Creating a new Code Object
Usually (but not always) handling is performed to create new code objects to add
to the registry (for information about code objects, see {file:docs/CodeObjects.md this document}).
Code objects should simply be created and added to the existing `namespace`. This
-will be enough to add them to the registry. There is also a convenience
+will be enough to add them to the registry. There is also a convenience
{YARD::Handlers::Base#register register} method which quickly sets standard attributed
on the newly created object, such as the file, line, source and docstring of the
object. This method will be seen in the next example.
-
+
### Handling an Inner Block
By default, the parser gives the processor class a list of all the top level
@@ -107,7 +107,7 @@ the following commands:
class YARD::Handlers::Ruby::ModuleHandler < YARD::Handlers::Ruby::Base
handles :module
-
+
def process
modname = statement[0].source
mod = register ModuleObject.new(namespace, modname)
@@ -126,27 +126,27 @@ Because the legacy handler uses the legacy parser and therefore a different kind
of AST, there are subtle differences in the handler API. Most importantly, the
`handles` method usually deals with either lexical tokens or source code as a string
or RegExp object. The statement object, similarly, is made up of lexical tokens instead
-of semantically parsed nodes (this is described in the {file:docs/Parser.md parser document}).
+of semantically parsed nodes (this is described in the {file:docs/Parser.md parser document}).
The module example above can be rewritten as a legacy handler as follows:
class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
handles TkMODULE
-
+
def process
modname = statement.tokens.to_s[/^module\s+(#{NAMESPACEMATCH})/, 1]
mod = register ModuleObject.new(namespace, modname)
parse_block(:namespace => mod)
end
end
-
+
A few notes on the differences:
* We inherit from `Legacy::Base` instead of the standard Ruby Base handler class.
* We exchange node type `:module` for `TkMODULE`, which represents the
- first token in the statement.
- * We perform direct string manipulation to get the module name.
- * `parse_block` does not take a list of statements. In the old parser API,
- each statement has a `block` attribute which defines the list of
- statements within that statement, if any. Therefore, `parse_block` will
+ first token in the statement.
+ * We perform direct string manipulation to get the module name.
+ * `parse_block` does not take a list of statements. In the old parser API,
+ each statement has a `block` attribute which defines the list of
+ statements within that statement, if any. Therefore, `parse_block` will
always parse the `statement.block` if it exists.
View
14 docs/Overview.md
@@ -11,14 +11,14 @@ that tools like RDoc do not do. These components are:
* [Data Storage Component](#storage)
* [Post Processing & Templating System](#templates)
-This separation is a major goal of the project, and means that YARD is not *just*
-a tool to generate HTML output. The expectation is that any subset of YARD's
-major components may be used, extended or modified independently. YARD may be
-used just as a data gathering tool (to parse and audit code), just as a data
-source (a webserver containing raw unformatted data about code), or just as a
+This separation is a major goal of the project, and means that YARD is not *just*
+a tool to generate HTML output. The expectation is that any subset of YARD's
+major components may be used, extended or modified independently. YARD may be
+used just as a data gathering tool (to parse and audit code), just as a data
+source (a webserver containing raw unformatted data about code), or just as a
conventional HTML documentation generation tool (like RDoc).
-The important classes and dependencies of these components are shown in the
+The important classes and dependencies of these components are shown in the
following class diagram:
![Overview Class Diagram](images/overview-class-diagram.png)
@@ -37,7 +37,7 @@ tasks during the data gathering process (*note: the tag architecture is not*
* {file:docs/Tags.md}
The parser component reads source files and converts it into a set of statements
-which the handlers then process, creating code objects which in turn create tags
+which the handlers then process, creating code objects which in turn create tags
(meta-data) attached to the objects. These objects are all added to the {YARD::Registry},
the data store component.
View
60 docs/Parser.md
@@ -7,7 +7,7 @@ that runs before any handling is done on the source. The parser is meant to tran
the source into a set of statements that can be understood by the {file:docs/Handlers.md Handlers}
that run immediately afterwards.
-The important classes are described in the class diagram of the entire parser
+The important classes are described in the class diagram of the entire parser
system below:
![Parser Class Diagram](images/parser-class-diagram.png)
@@ -23,7 +23,7 @@ to parsing methods). YARD supports Ruby and C source files, but custom parsers c
be implemented and registered for various other languages by subclassing `Parser::Base`
and registering the parser with {YARD::Parser::SourceParser.register_parser_type}.
-This factory class should always be used when parsing source files rather than
+This factory class should always be used when parsing source files rather than
the individual parser classes since it initiates the pipeline that runs the
handlers on the parsed source. The parser used must also match the handlers,
and this is coordinated by the `SourceParser` class as well.
@@ -36,48 +36,48 @@ array of file globs or a single file glob.
YARD::Parser::SourceParser.parse('spec_*.rb')
YARD::Parser::SourceParser.parse(['spec_*.rb', '*_helper.rb'])
-
+
This is equivalent to the convenience method {YARD.parse}:
YARD.parse('lib/**/*.rb')
-
+
In some cases (ie. for testing), it may be more helpful to parse a string of input
directly. In such a case, the method {YARD::Parser::SourceParser.parse_string} should be
used:
YARD::Parser::SourceParser.parse_string("def method(a, b) end")
-
+
You can also provide the parser type explicitly as the second argument:
# Parses a string of C
YARD::Parser::SourceParser.parse_string("int main() { }", :c)
-
-Note that these two methods are aliased as {YARD.parse} and {YARD.parse_string} for
+
+Note that these two methods are aliased as {YARD.parse} and {YARD.parse_string} for
convenience.
-
+
## Implementing and Registering a Custom Parser
To implement a custom parser, subclass {YARD::Parser::Base}. Documentation on which
abstract methods should be implemented are documented in that class. After the class
is implemented, it is registered with the {YARD::Parser::SourceParser} factory class
to be called when a file of the right extension needs to be parsed, or when a user
-selects that parser type explicitly. To register your new parser class, call the
+selects that parser type explicitly. To register your new parser class, call the
method {YARD::Parser::SourceParser.register_parser_type}:
SourceParser.register_parser_type(:my_parser, MyParser, 'my_parser_ext')
-
+
The last argument can be a single extension, a list of extensions (Array), a single Regexp, or a
list of Regexps. Do not include the '.' in the extension.
## The Two Ruby Parser Types
When parsing Ruby, the SourceParser can either instantiate the new {YARD::Parser::Ruby::RubyParser}
-class or the {YARD::Parser::Ruby::Legacy::StatementList} class. The first of the
-two, although faster, more robust and more efficient, is only available for
-Ruby 1.9. The legacy parser parser is available in both 1.8.x and 1.9, if
-compatibility is required. The choice of parser will affect which handlers
-ultimately get used, since new handlers can only use the new parser and the
+class or the {YARD::Parser::Ruby::Legacy::StatementList} class. The first of the
+two, although faster, more robust and more efficient, is only available for
+Ruby 1.9. The legacy parser parser is available in both 1.8.x and 1.9, if
+compatibility is required. The choice of parser will affect which handlers
+ultimately get used, since new handlers can only use the new parser and the
same requirement applies to the legacy parser & handlers.
## Switching to Legacy Parser
@@ -89,7 +89,7 @@ only the legacy handlers are implemented, the `SourceParser` class should force
the use of the legacy parser by setting the `parser_type` attribute as such:
YARD::Parser::SourceParser.parser_type = :ruby18
-
+
The default value is `:ruby`. Note that this cannot be forced the other way around,
a parser type of `:ruby` cannot be set under Ruby 1.8.x as the new parser is not
supported under 1.8.
@@ -114,36 +114,36 @@ by the `#type` method. The following examples show some of the basic uses of `As
node.type #=> :if_mod
node[0] #=> s(:int, "1")
node[0][0] #=> "1"
-
+
(Note the `s()` syntax is shorthand for `AstNode.new(...)`. `s()` with no type
is shorthand for a node of type `:list`)
-As shown, not all of the elements are AstNodes in themselves, some are String
-objects containing values. A list of only the AstNodes within a node can be
+As shown, not all of the elements are AstNodes in themselves, some are String
+objects containing values. A list of only the AstNodes within a node can be
accessed via the {YARD::Parser::Ruby::AstNode#children #children} method. Using
the sexp declared above, we can do:
node.children #=> [s(:int, "1"), s(:var_ref, s(:ident, "hello"))]
### AstNode#source and #line
-Every node defines the `#source` method which returns the source code that the
-node represents. One of the most common things to do with a node is to grab its
+Every node defines the `#source` method which returns the source code that the
+node represents. One of the most common things to do with a node is to grab its
source. The following example shows how this can be done:
source = "if 1 == 1 then\n raise Exception\n end"
ast = YARD::Parser::Ruby::RubyParser.parse(source).root
ast[0].condition.source #=> "1 == 1"
ast[0].then_block.source #=> "raise Exception"
-
+
Note that this only works on source parsed from the RubyParser, not sexps
declared using the `s()` syntax. This is because no source code is generated
or stored by nodes. Instead, only the character ranges are stored, which are
then looked up in the original full source string object. For example:
# Following the code snippet above
- ast[0].then_block.source_range #=> 17..31
-
+ ast[0].then_block.source_range #=> 17..31
+
We can also get the line and line ranges in a similar fashion:
ast[0].type #=> :if
@@ -159,19 +159,19 @@ to quickly get at a node of a specific type in such a situation:
# Get the first identifier in the statement
ast = s(s(:int, "1"), s(s(:var_ref, s(:ident, "hello"))))
ast.jump(:ident)[0] #=> "hello"
-
+
Multiple types can be searched for at once. If none are found, the original root
node is returned so that it may be chained.
## The Legacy Parser
The goal of the legacy parser is much the same as the new parser, but it is far
more simplistic. Instead of a full-blown AST, the legacy parser simply groups
-together lists of "statements" called a {YARD::Parser::Ruby::Legacy::StatementList}.
+together lists of "statements" called a {YARD::Parser::Ruby::Legacy::StatementList}.
These statement lists are made up of {YARD::Parser::Ruby::Legacy::Statement} objects.
-A statement is any method call condition, loop, or declaration. Each statement
-may or may not have a block. In the case of a condition or loop, the block is
-the inner list of statements; in the case of a method call, the block is a do
+A statement is any method call condition, loop, or declaration. Each statement
+may or may not have a block. In the case of a condition or loop, the block is
+the inner list of statements; in the case of a method call, the block is a do
block (if provided). The statements themselves are made up of tokens, so instead
of being semantic in nature like the new parser, statements are tied directly
to the lexical tokens that make them up. To convert a statement into source, you
@@ -185,7 +185,7 @@ but using the legacy parser it is only one statement:
stmts = ARD::Parser::Ruby::Legacy::StatementList.new("hello if 1")
stmts[0].block #=> nil
stmts[0].tokens.to_s #=> "hello if 1"
-
+
In addition, this means that most handling still needs to be done via string
manipulation and regular expression matching, making it considerably more
difficult to use in edge case scenarios.
View
8 docs/Tags.md
@@ -2,7 +2,7 @@
# Tags Overview
-Tags represent meta-data as well as behavioural data that can be added to
+Tags represent meta-data as well as behavioural data that can be added to
documentation through the `@tag` style syntax. As mentioned, there are two
basic types of tags in YARD, "meta-data tags" and "behavioural tags", the
latter is more often known as "directives". These two tag types can be
@@ -68,7 +68,7 @@ is considered free-form data and can include any arbitrary textual data.
### Multi-line Tags
-Tags can span multiple lines if the subsequent lines are indented by more than
+Tags can span multiple lines if the subsequent lines are indented by more than
one space. The typical convention is to indent subsequent lines by 2 spaces.
In the following example, `@tagname` will have the text *"This is indented tag data"*:
@@ -78,7 +78,7 @@ In the following example, `@tagname` will have the text *"This is indented tag d
For most tags, newlines and indented data are not significant and do not impact
the result of the tag. In other words, you can decide to span a tag onto multiple
-lines at any point by creating an indented block. However, some tags like
+lines at any point by creating an indented block. However, some tags like
{tag:example}, {tag:overload}, {tag:!macro}, {tag:!method}, and {tag:!attribute}
rely on the first line for special information about the tag, and you cannot
split this first line up. For instance, the {tag:example} tag uses the first line
@@ -193,7 +193,7 @@ that responds to the "read" method:
# @param [#read] io the input object to read from
def read(io) io.read end
-#### Hashes
+#### Hashes
Hashes can be specified either via the parametrized type discussed above,
in the form `Hash<KeyType, ValueType>`, or using the hash specific syntax:
View
116 docs/Templates.md
@@ -29,32 +29,32 @@ The design goals can be summarized as follows:
3. Sections should be able to be inserted into any object without affecting
any existing sections in the document. This allows for easy modification
of templates by plugins.
-
+
## Templates
-Template modules are the objects used to orchestrate the design goals listed
+Template modules are the objects used to orchestrate the design goals listed
above. Specifically, they organize the sections and render the template contents
-depending on the format.
+depending on the format.
## Engine
-The Engine class orchestrates the creation and rendering of Template modules and
+The Engine class orchestrates the creation and rendering of Template modules and
handles serialization or specific rendering scenarios (like HTML). To create
-a template, use the {YARD::Templates::Engine.template template} method. The two most
-common methods used to initiate output are the {YARD::Templates::Engine.render render}
-and {YARD::Templates::Engine.generate generate} methods which generate and
-optionally serialize output to a file. The latter, `#generate`, is used
-specially to generate HTML documentation and copy over assets that may be
+a template, use the {YARD::Templates::Engine.template template} method. The two most
+common methods used to initiate output are the {YARD::Templates::Engine.render render}
+and {YARD::Templates::Engine.generate generate} methods which generate and
+optionally serialize output to a file. The latter, `#generate`, is used
+specially to generate HTML documentation and copy over assets that may be
needed. For instance, an object may be rendered with:
YARD::Templates::Engine.render(:object => myobject)
-
+
A set of objects may be rendered into HTML documentation by using:
# all_objects is an array of module and class objects
# options includes a :serializer key to copy output to the file system
YARD::Templates::Engine.generate(all_objects, options)
-
+
Note that these methods should not be called directly. The {YARD::CodeObjects::Base}
class has a {YARD::CodeObjects::Base#format #format} helper method to render an
object. For instance, the above render example is equivalent to the simple
@@ -67,11 +67,11 @@ A template keeps state when it is rendering output. This state is kept in
an options hash which is initially passed to it during instantiation. Some
default options set the template style (`:template`), the output format (`:format`),
and the serializer to use (`:serializer`). This options hash is modifiable
-from all methods seen above. For example, initializing a template to output as
+from all methods seen above. For example, initializing a template to output as
HTML instead of text can be done as follows:
myobject.format(:format => :html)
-
+
## Serializer
This class abstracts the logic involved in deciding how to serialize data to
@@ -82,7 +82,7 @@ are used (like files or URLs), the serializer implements the {YARD::Serializers:
method. This allows the translation from a code object to its path at the endpoint,
which enables inter-document linking.
-Rendered objects are automatically serialized using the object if present,
+Rendered objects are automatically serialized using the object if present,
otherwise the rendered object is returned as a string to its parent. Nested
Templates automatically set the serializer to nil so that they return
as a String to their parent.
@@ -120,22 +120,22 @@ on disk. A standard template directory looks like the following tree:
| |-- index.erb
| `-- text.erb
-The path `default` refers to the template style (:template key in options hash)
+The path `default` refers to the template style (:template key in options hash)
and the directories at the next level (such as `class`) refer to template
-`:type` (options hash key) for a template. The next directory refers to the
-output format being used defined by the `:format` template option.
+`:type` (options hash key) for a template. The next directory refers to the
+output format being used defined by the `:format` template option.
As we saw in the above example, the format option can be set to `:html`, which
-would use the `html/` directory instead of `text/`. Finally, the individual .erb
+would use the `html/` directory instead of `text/`. Finally, the individual .erb
files are the sections that make up the template.
Note that the subdirectory `html/` is also its own "template" that inherits
from the parent directory. We will see more on this later.
## setup.rb
-Every template should have at least one `setup.rb` file that defines the
-{YARD::Templates::Template#init #init} method to set the
+Every template should have at least one `setup.rb` file that defines the
+{YARD::Templates::Template#init #init} method to set the
{YARD::Templates::Template#sections #sections} used by the template. If
a setup.rb is not defined in the template itself, there should be a template
that is inherited (via parent directory or explcitly) that sets the sections
@@ -150,9 +150,9 @@ A standard setup.rb file looks like:
## Sections
Sections are smaller components that correlate to template
-fragments. Practically speaking, a section can either be a template fragment
-(a conventional .erb file or other supported templating language), a method
-(which returns a String) or another {YARD::Templates::Template} (which in turn has its own
+fragments. Practically speaking, a section can either be a template fragment
+(a conventional .erb file or other supported templating language), a method
+(which returns a String) or another {YARD::Templates::Template} (which in turn has its own
list of sections).
## Nested Sections
@@ -165,7 +165,7 @@ a section, for example:
def init
sections :header, [:section_a, :section_b]
end
-
+
The above example nests `section_a` and `section_b` within the `header` section.
Practically speaking, these sections can be placed in the result by `yield`ing
to them. A sample header.erb template might contain:
@@ -174,7 +174,7 @@ to them. A sample header.erb template might contain:
<div id="contents">
<%= yieldall %>
</div>
-
+
This template code would place the output of `section_a` and `section_b` within
the above div element. Using `yieldall`, we can also change the object that is being
rendered. For example, we may want to yield the first method of the class.
@@ -197,7 +197,7 @@ more accurate) by the current template. This means that the 'default/class/html'
template automatically inherits from 'default/class'. This also means that anything
defined in 'default/class/setup.rb' can be overridden by 'default/class/html/setup.rb'.
-Since the Template module is a module, and not a class, they can be mixed in
+Since the Template module is a module, and not a class, they can be mixed in
explicitly (via include/extend) from other templates, which allows templates
to share erb files or helper logic. The 'default/class' template explicitly
mixes in the 'default/module' template, since it uses much of the same sections.
@@ -225,29 +225,29 @@ instance, will modify the #init method to insert class specific sections:
sections.delete(:children)
sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)
end
-
+
Observe how sections has been modified after the super method was called (the
super method would have been defined in `default/module/setup.rb`). The
`sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
-before or after another section using {Array#place} by it's given name rather
+before or after another section using {Array#place} by it's given name rather
than index. This allows the overriding of templates in a way that does not
-depend on where the section is located (since it may have been overriden by
+depend on where the section is located (since it may have been overriden by
another module).
You can also use `sections[:name]` to find the first child section named `:name`.
For instance, with the following sections declaration:
sections :a, [:b, :c, [:d]]
-
+
You can get to the :d section with:
sections[:a][:c][:d]
-
+
You can use this to insert a section inside a nested set without using indexed
access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:
sections[:a][:c].place(:e).after(:d)
-
+
There are also two methods, {Insertion#before_any} and {Insertion#after_any},
which allow you to insert sections before or after the first matching section name
recursively. The above example could simply be rewritten as:
@@ -265,16 +265,16 @@ YARD solves this problem by allowing other template paths to be registered.
Because template modules are represented by a relative path such as 'default/class',
they can be found within any of the registered template paths. A new template
path is registered as:
-
+
YARD::Templates::Engine.register_template_path '/path/to/mytemplates'
-
+
At this point, any time the 'default/class' template is loaded, the template
will first be looked for inside the newly registered template path. If found,
it will be used as the template module, with the modules from the other
-template paths implicitly mixed in.
+template paths implicitly mixed in.
Therefore, by using the same directory structure as a builtin YARD template,
-a user can customize or override individual templates as if the old ones were
+a user can customize or override individual templates as if the old ones were
inherited. A real world example would further modify the 'default/class' template
seen above by creating such a path in our '/path/to/mytemplates' custom template
path:
@@ -292,7 +292,7 @@ The `setup.rb` file would look like:
sections.push :customsection
end
-Now, when a class object is formatted as HTML, our customsection.erb will be
+Now, when a class object is formatted as HTML, our customsection.erb will be
appended to the rendered data.
@@ -344,7 +344,7 @@ The `jquery.js` is copy of the jquery javascript library.
To load additional stylesheets and javascripts with every page (except the search
field menus) generated from the base `layout` template:
- 1. Define your own custom stylesheet and/or javascript file
+ 1. Define your own custom stylesheet and/or javascript file
(default/ is the default template name inside of the /template root directory):
/template/default/:
@@ -355,28 +355,28 @@ field menus) generated from the base `layout` template:
| | |-- js
| | | |-- custom.js
- 2. Create a `setup.rb` in the `layout` template directory and override the methods
+ 2. Create a `setup.rb` in the `layout` template directory and override the methods
`stylesheets` and `javascripts`. The path to the template would be:
-
+
/template/default/:
|-- layout
| |-- html
| | |-- setup.rb
-
+
And the code would look like:
-
+
def stylesheets
# Load the existing stylesheets while appending the custom one
super + %w(css/custom.css)
end
-
+
def javascripts
# Load the existing javascripts while appending the custom one
super + %w(js/custom.js)
end
-
-To load additional stylesheets and javascripts for the search menus loaded from
+
+To load additional stylesheets and javascripts for the search menus loaded from
the `fulldoc` template:
1. Define your own custom stylesheet and/or javascript file.
@@ -416,21 +416,21 @@ Their contents are rendered in methods within the `fulldoc` template:
* `generate_class_list`
* `generate_method_list`
* `generate_file_list`
-
+
To override these lists you will need to:
1. Create a `setup.rb` in the `fulldoc` template directory and override the
particular method.
-
+
/path/to/mytemplates/:
|-- fulldoc
| |-- html
| | |-- setup.rb
-
+
def generate_method_list
@items = prune_method_listing(Registry.all(:method), false)
@items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
-
+
# Here we changed the functionality to reverse the order of displayed methods
@items = @items.sort_by {|m| m.name.to_s }.reverse
@list_title = "Method List"
@@ -452,11 +452,11 @@ the `fulldoc` template through a similarly named method.
To load an additional menu item:
- 1. Create a `setup.rb` in the `layout` template directory and override the methods
+ 1. Create a `setup.rb` in the `layout` template directory and override the methods
`menu_lists`. The `type` informs the search field the name of the file.
The `title` is the name that appears above the section when viewed in frames.
The `search_title` is the name that appears in the search field tab on the page.
-
+
/path/to/mytemplates/:
|-- layout
@@ -467,29 +467,29 @@ To load an additional menu item:
# Load the existing menus
super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]
end
-
+
2. Create a `setup.rb` in the `fulldoc` template directory and create a method
- to generate a menu for the specified `type`.
+ to generate a menu for the specified `type`.
The method `generate_assets` will look for a function with a signature prefixed
- with `generate`, the type value specified, and the suffix `list`. Within that
+ with `generate`, the type value specified, and the suffix `list`. Within that
method you can configure and load the specific objects you wish to display.
-
+
/path/to/mytemplates/:
|-- fulldoc
| |-- html
| | |-- setup.rb
def generate_feature_list
-
+
# load all the features from the Registry
@items = Registry.all(:feature)
@list_title = "Feature List"
@list_type = "feature"
-
+
# optional: the specified stylesheet class
# when not specified it will default to the value of @list_type
@list_class = "class"
-
+
# Generate the full list html file with named feature_list.html
# @note this file must be match the name of the type
asset('feature_list.html', erb(:full_list))
View
266 docs/WhatsNew.md
@@ -33,16 +33,16 @@ or attributes in your class. Consider DataMapper's "property" declaration:
# @return [String] the title of the post
property :title, String
end
-
+
The above declaration would be created as the `Post#title`. The optional
`@attribute` tag tells YARD that the property is an "attribute", and not just
a regular method.
In addition to basic DSL method detection, YARD also supports macros to create
-docstrings that can be copies to other objects; these macros can also be
+docstrings that can be copies to other objects; these macros can also be
"attached" to class level methods to create implicit documentation for macros.
-Macros and DSL method detection are discussed in much more detail in the
+Macros and DSL method detection are discussed in much more detail in the
{file:docs/GettingStarted.md}, so you should read about them there if you're
interested in this feature.
@@ -53,10 +53,10 @@ template in the same manner that inherited methods do.
## The 'app' directory is now parsed by default (0.7.0)
-YARD tries to follow the "It Just Works" attitude in writing developer tools,
+YARD tries to follow the "It Just Works" attitude in writing developer tools,
and therefore has added `app/**/*.rb` to the default list of globs that it
searches for code in. You no longer need to create a `.yardopts` just to
-list your app directory when documenting your code on rubydoc.info.
+list your app directory when documenting your code on rubydoc.info.
We should have done this a while ago! And don't worry, YARD still checks
lib and ext by default, too.
@@ -65,22 +65,22 @@ lib and ext by default, too.
Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now support
metadata tags, just like docstrings in code comments. By adding @tag values
to the top of a file (no whitespace preceding it) inside of a `# comment` line,
-YARD will detect and parse these tags and store it for later usage.
+YARD will detect and parse these tags and store it for later usage.
-Tags can contain arbitrary data as well as arbitrary tag names, however the
-tag names @title and @markup are reserved to specify the document title and
+Tags can contain arbitrary data as well as arbitrary tag names, however the
+tag names @title and @markup are reserved to specify the document title and
markup format respectively. The title will be used in the file list menu,
index page, as well as any linking of the file via the `{file:Filename}`
syntax. An example of a document with metadata would be:
# @title The Best Project Ever!
# @markup rdoc
# @author Foo Bar (custom tag, does not display in templates)
-
+
= This Project Rules
-
+
== Contents
-
+
...
Note that previous versions of YARD recommended specifying the markup of an
@@ -93,7 +93,7 @@ The `yardoc --list` command is used to list objects that are parsed from
a codebase. This can be used to grep methods/classes in a codebase from the
command line. `yard list` now calls `yardoc --list` as a convenience command.
-Note that the `yardoc --list` command may eventually be replaced by a more
+Note that the `yardoc --list` command may eventually be replaced by a more
feature-filled `yard list` command, so `yard list` should be used instead of
`yardoc --list` when possible.
@@ -117,7 +117,7 @@ Ruby source files and performing syntax highlighting on the code.
## Added `{render:OBJECT}` syntax to embed object docs in extra files (0.7.0)
-You can now use the `{render:Object}` syntax to embed the documentation
+You can now use the `{render:Object}` syntax to embed the documentation
rendering of an entire object (method, class, module) inside of an extra file.
This is useful when writing non-API based guides that might require listing
a few helper methods or classes. The {file:docs/GettingStarted.md} discussed
@@ -140,7 +140,7 @@ above.
## Added state tracking variables to Parser/Handler architecture (0.7.0)
-The parser and handler architecture now contain state variables
+The parser and handler architecture now contain state variables
{YARD::Handlers::Base#extra_state} and {YARD::Handlers::Processor#globals}
to share data across handlers and the entire processing phase. `#extra_state`
provided a place to store per-file data, while `#globals` gives the developer
@@ -220,7 +220,7 @@ markup types:
* pre: Used to wrap text inside `<pre>` tags
* text: No formatting except for hard breaks (`<br>`) on newlines
* none: No formatting at all.
-
+
In all cases, HTML is escaped from input. If you want no HTML escaping, use the
html markup type.
@@ -255,109 +255,109 @@ for aliases is not supported, however.
## Local documentation server for RubyGems or projects (`yard server`) (0.6.0)
The new `yard server` command spawns a documentation server that can serve
-either documentation for a local project or installed RubyGems. The server
-will host (by default) on http://localhost:8808.
+either documentation for a local project or installed RubyGems. The server
+will host (by default) on http://localhost:8808.
To serve documentation for the active project (in the current directory):
$ yard server
-
-The server can also run in "incremental" mode for local projects. In this
-situation, any modified sources will immediately be updated at each request,
-ensuring that the server always serve the code exactly as it is on disk.
-Documenting your code in this fashion essentially gives you an efficient a
-live preview without running a separate command everytime you make a change.
+
+The server can also run in "incremental" mode for local projects. In this
+situation, any modified sources will immediately be updated at each request,
+ensuring that the server always serve the code exactly as it is on disk.
+Documenting your code in this fashion essentially gives you an efficient a
+live preview without running a separate command everytime you make a change.
To serve documentation for the active project in incremental mode:
$ yard server --reload
-
-<span class="note">Note that in incremental mode, objects or method groupings
- cannot be removed. If you have removed objects or modified groupings, you
- will need to flush the cache by deleting `.yardoc` and (optionally)
+
+<span class="note">Note that in incremental mode, objects or method groupings
+ cannot be removed. If you have removed objects or modified groupings, you
+ will need to flush the cache by deleting `.yardoc` and (optionally)
restarting the server.</span>
-The documentation server can also serve documentation for all installed gems
-on your system, similar to `gem server`, but using YARD's functionality and
+The documentation server can also serve documentation for all installed gems
+on your system, similar to `gem server`, but using YARD's functionality and
templates. To serve documentation for installed gems:
$ yard server --gems
-
-<span class="note">Documentation for the gem need not be previously generated
- at install-time. If documentation for the gem has not been generated, YARD
- will do this for you on-the-fly. It is therefore possible to speed up your
+
+<span class="note">Documentation for the gem need not be previously generated
+ at install-time. If documentation for the gem has not been generated, YARD
+ will do this for you on-the-fly. It is therefore possible to speed up your
gem installs by using `gem install GEMNAME --no-rdoc` without repercussion.
You can also add this switch to your `~/.gemrc` file so that you don't need
- to re-type it each time. See [this link](http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)
+ to re-type it each time. See [this link](http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install)
for exact instructions.</span>
## Groups support for method listing (0.6.0)
-You can now organize methods in a class/module into logical separated groups.
-These groups apply lexically and are listed in the order they are defined.
+You can now organize methods in a class/module into logical separated groups.
+These groups apply lexically and are listed in the order they are defined.
For instance, to define a group:
# @group Rendering an Object
-
+
# Documentation here
def foo; end
-
+
# Extra documentation...
def bar; end
-
+
# @group Another Group
-
+
def aaa; end
-
-<span class="note">Note that these `@group` and `@endgroup` declarations are
- not "tags" and should always be separated with at least 1 line of whitespace
+
+<span class="note">Note that these `@group` and `@endgroup` declarations are
+ not "tags" and should always be separated with at least 1 line of whitespace
from any other documentation or code.</span>
-
-In the above example, "Rendering an Object" will be listed with "foo" and
-"bar" above "Another Group", even though "aaa" comes before the two other
-methods, alphabetically. To end a group, use `@endgroup`. It is not necessary
-to end a group to start a new one, only if there is an object following the
+
+In the above example, "Rendering an Object" will be listed with "foo" and
+"bar" above "Another Group", even though "aaa" comes before the two other
+methods, alphabetically. To end a group, use `@endgroup`. It is not necessary
+to end a group to start a new one, only if there is an object following the
group that should not belong in any group.
# @group Group 1
-
+
def foo; end
-
+
# @endgroup
-
+
# This method should not be listed in any group
def bar; end
## Single file template (`--one-file`) support (0.6.0)
-`yardoc` now has the `--one-file` option to generate a single-file template
-for small scripts and libraries. In this case, any comments at the top of
+`yardoc` now has the `--one-file` option to generate a single-file template
+for small scripts and libraries. In this case, any comments at the top of
the script file will be recognized as a README.
## `yard` CLI executable with pluggable commands (0.6.0)
-<span class="note">The `yardoc` and `yri` commands are not deprecated and can
- continue to be used. They are shortcuts for `yard doc` and `yard ri`
+<span class="note">The `yardoc` and `yri` commands are not deprecated and can
+ continue to be used. They are shortcuts for `yard doc` and `yard ri`
respectively. However, `yard-graph` has been removed.</span>
-YARD now has a `yard` executable which combines all pre-existing and new
-commands into a single pluggable command that is both easier to remember and
+YARD now has a `yard` executable which combines all pre-existing and new
+commands into a single pluggable command that is both easier to remember and
access. To get a list of commands, type `yard --help`.
-If you are a plugin developer, you can create your own `yard` command by first
-subclassing the {YARD::CLI::Command} class and then registering this class
+If you are a plugin developer, you can create your own `yard` command by first
+subclassing the {YARD::CLI::Command} class and then registering this class
with the {YARD::CLI::CommandParser.commands} list. For instance:
YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass
-
+
The above line will enable the user to execute `yard my_command [options]`.
## `yard diff` command to object-diff two versions of a project (0.6.0)
-One of the built-in commands that comes with the new `yard` executable is the
-ability to do object-oriented diffing across multiple versions of the same
-project, either by 2 versions of a gem, or 2 working copies. Just like
-regular diffing tells you which lines have been added/removed in a file,
-object diffing allows you to see what classes/methods/modules have been
+One of the built-in commands that comes with the new `yard` executable is the
+ability to do object-oriented diffing across multiple versions of the same
+project, either by 2 versions of a gem, or 2 working copies. Just like
+regular diffing tells you which lines have been added/removed in a file,
+object diffing allows you to see what classes/methods/modules have been
added/removed between versions of a codebase.
For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](http://gnuu.org/2010/06/26/yard-object-oriented-diffing/).
@@ -372,87 +372,87 @@ YARD now outputs the following statistics when `yard stats` is run:
Constants: 53 ( 20 undocumented)
Methods: 602 ( 70 undocumented)
85.16% documented
-
-Note that these statistics are based on what you have set to show in your
-documentation. If you use `@private` tags and/or do not display
-private/protected methods in your documentation, these will not show up as
+
+Note that these statistics are based on what you have set to show in your
+documentation. If you use `@private` tags and/or do not display
+private/protected methods in your documentation, these will not show up as
undocumented. Therefore this metric is contextual.
-You can also specifically list all undocumented objects (and their file
+You can also specifically list all undocumented objects (and their file
locations) with the `--list-undoc` option.
## Added `--asset` option to `yardoc` (0.6.0)
-The `yardoc` command can now take the `--asset` option to copy over
-files/directories (recursively) to the output path after generating
-documentation. The format of the argument is "from:to" where from is the
-source path and to is the destination. For instance, YARD uses the following
-syntax in the `.yardopts` file to copy over image assets from the
+The `yardoc` command can now take the `--asset` option to copy over
+files/directories (recursively) to the output path after generating
+documentation. The format of the argument is "from:to" where from is the
+source path and to is the destination. For instance, YARD uses the following
+syntax in the `.yardopts` file to copy over image assets from the
'docs/images' directory into the 'images' directory after generating HTML:
--asset docs/images:images
## New template API (0.6.0)
-The new template API allows for easier insertion of sections within an
-inherited template. You should no longer need to insert by index, an
+The new template API allows for easier insertion of sections within an
+inherited template. You should no longer need to insert by index, an
error-prone process that could break when a template is updated. Instead of:
sections.last.place(:my_section).before(:another_section)
use:
sections.place(:my_section).before_any(:another_section)
-
+
You can see more in the {file:docs/Templates.md#Inserting_and_Traversing_Sections}
document.
## HTML template now adds inline Table of Contents for extra files pages (0.6.0)
-A table of contents is now generated dynamically using JavaScript for extra
+A table of contents is now generated dynamically using JavaScript for extra
file pages (such as README's, or this document). It is generated based off the
-headers (h1,h2,... tags) used in the document, and can be floated to the
+headers (h1,h2,... tags) used in the document, and can be floated to the
right or listed inline on the page.
## Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.) (0.6.0)
-Simple meta-data tags can now be added at the command-line and registered to
-display in templates in a number of pre-defined ways. For instance, to create
+Simple meta-data tags can now be added at the command-line and registered to
+display in templates in a number of pre-defined ways. For instance, to create
a freeform text tag, use the following:
--tag my_tag_name:"My Tag Title"
-
-You can also create a "typed" tag (similar to `@return`), a typed named tag
-(similar to `@param`) as well as various combinations. The full list of
+
+You can also create a "typed" tag (similar to `@return`), a typed named tag
+(similar to `@param`) as well as various combinations. The full list of
options are listed in `yardoc --help` under the "Tag Options" section.
-
-If you wish to create a tag to store data but do not wish to show this data
+
+If you wish to create a tag to store data but do not wish to show this data
in the templates, use the `--hide-tag` option to hide it from generated output:
--hide-tag my_tag_name
## Added `--transitive-tags` to register transitive tags (0.6.0)
-Transitive tags are tags that apply to all descendants of a namespace (class
-or module) when documented on that namespace. For instance, the `@since` tag
-is a transitive tag. Applying `@since` to a class will automatically apply
-`@since` to all methods in the class. Creating a `@since` tag directly on a
+Transitive tags are tags that apply to all descendants of a namespace (class
+or module) when documented on that namespace. For instance, the `@since` tag
+is a transitive tag. Applying `@since` to a class will automatically apply
+`@since` to all methods in the class. Creating a `@since` tag directly on a
method will override the inherited value.
You can specify transitive tags on the command-line by using this option. Note
that the tags must already exist (built-in or created with the `--tag` option)
-to be specified as transitive. If you wish to do this programmatically, see
+to be specified as transitive. If you wish to do this programmatically, see
the {YARD::Tags::Library.transitive_tags} attribute.
## `yardoc` now displays RDoc-like statistics (`--no-stats` to hide) (0.6.0)
-As seen in the `yard stats` feature overview, `yardoc` displays RDoc-like
-statistics when it is run. The output is equivalent to typing `yard stats`.
+As seen in the `yard stats` feature overview, `yardoc` displays RDoc-like
+statistics when it is run. The output is equivalent to typing `yard stats`.
To hide this output when yardoc is run, use `--no-stats`.
## `yri` now works on constants (0.6.0)
-Templates have now been added for text view of constants, which displays any
+Templates have now been added for text view of constants, which displays any
documentation and the constant value.
## Plugins are no longer auto-loaded (added `--plugin` switch) (0.6.2)
@@ -461,14 +461,14 @@ This is a backwards-incompatible change that disables plugins from automatically