yard 0.9.29 → 0.9.30

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of yard might be problematic. Click here for more details.

Files changed (152) hide show
  1. checksums.yaml +4 -4
  2. data/docs/CodeObjects.md +115 -0
  3. data/docs/GettingStarted.md +679 -0
  4. data/docs/Handlers.md +152 -0
  5. data/docs/Overview.md +61 -0
  6. data/docs/Parser.md +191 -0
  7. data/docs/Tags.md +283 -0
  8. data/docs/TagsArch.md +123 -0
  9. data/docs/Templates.md +496 -0
  10. data/docs/WhatsNew.md +1245 -0
  11. data/docs/images/code-objects-class-diagram.png +0 -0
  12. data/docs/images/handlers-class-diagram.png +0 -0
  13. data/docs/images/overview-class-diagram.png +0 -0
  14. data/docs/images/parser-class-diagram.png +0 -0
  15. data/docs/images/tags-class-diagram.png +0 -0
  16. data/docs/templates/default/fulldoc/html/full_list_tag.erb +9 -0
  17. data/docs/templates/default/fulldoc/html/setup.rb +6 -0
  18. data/docs/templates/default/layout/html/setup.rb +9 -0
  19. data/docs/templates/default/layout/html/tag_list.erb +11 -0
  20. data/docs/templates/default/yard_tags/html/list.erb +18 -0
  21. data/docs/templates/default/yard_tags/html/setup.rb +26 -0
  22. data/docs/templates/plugin.rb +70 -0
  23. data/lib/yard/version.rb +1 -1
  24. data/po/ja.po +31108 -0
  25. data/templates/default/class/dot/setup.rb +7 -0
  26. data/templates/default/class/dot/superklass.erb +3 -0
  27. data/templates/default/class/html/constructor_details.erb +8 -0
  28. data/templates/default/class/html/setup.rb +2 -0
  29. data/templates/default/class/html/subclasses.erb +4 -0
  30. data/templates/default/class/setup.rb +36 -0
  31. data/templates/default/class/text/setup.rb +12 -0
  32. data/templates/default/class/text/subclasses.erb +5 -0
  33. data/templates/default/constant/text/header.erb +11 -0
  34. data/templates/default/constant/text/setup.rb +4 -0
  35. data/templates/default/docstring/html/abstract.erb +4 -0
  36. data/templates/default/docstring/html/deprecated.erb +1 -0
  37. data/templates/default/docstring/html/index.erb +5 -0
  38. data/templates/default/docstring/html/note.erb +6 -0
  39. data/templates/default/docstring/html/private.erb +4 -0
  40. data/templates/default/docstring/html/returns_void.erb +1 -0
  41. data/templates/default/docstring/html/text.erb +1 -0
  42. data/templates/default/docstring/html/todo.erb +6 -0
  43. data/templates/default/docstring/setup.rb +52 -0
  44. data/templates/default/docstring/text/abstract.erb +2 -0
  45. data/templates/default/docstring/text/deprecated.erb +2 -0
  46. data/templates/default/docstring/text/index.erb +2 -0
  47. data/templates/default/docstring/text/note.erb +4 -0
  48. data/templates/default/docstring/text/private.erb +2 -0
  49. data/templates/default/docstring/text/returns_void.erb +1 -0
  50. data/templates/default/docstring/text/text.erb +1 -0
  51. data/templates/default/docstring/text/todo.erb +4 -0
  52. data/templates/default/fulldoc/html/css/common.css +1 -0
  53. data/templates/default/fulldoc/html/css/full_list.css +58 -0
  54. data/templates/default/fulldoc/html/css/style.css +497 -0
  55. data/templates/default/fulldoc/html/frames.erb +17 -0
  56. data/templates/default/fulldoc/html/full_list.erb +37 -0
  57. data/templates/default/fulldoc/html/full_list_class.erb +2 -0
  58. data/templates/default/fulldoc/html/full_list_file.erb +7 -0
  59. data/templates/default/fulldoc/html/full_list_method.erb +10 -0
  60. data/templates/default/fulldoc/html/js/app.js +314 -0
  61. data/templates/default/fulldoc/html/js/full_list.js +216 -0
  62. data/templates/default/fulldoc/html/js/jquery.js +4 -0
  63. data/templates/default/fulldoc/html/setup.rb +241 -0
  64. data/templates/default/layout/dot/header.erb +6 -0
  65. data/templates/default/layout/dot/setup.rb +15 -0
  66. data/templates/default/layout/html/breadcrumb.erb +11 -0
  67. data/templates/default/layout/html/files.erb +11 -0
  68. data/templates/default/layout/html/footer.erb +5 -0
  69. data/templates/default/layout/html/headers.erb +15 -0
  70. data/templates/default/layout/html/index.erb +2 -0
  71. data/templates/default/layout/html/layout.erb +24 -0
  72. data/templates/default/layout/html/listing.erb +4 -0
  73. data/templates/default/layout/html/objects.erb +32 -0
  74. data/templates/default/layout/html/script_setup.erb +4 -0
  75. data/templates/default/layout/html/search.erb +13 -0
  76. data/templates/default/layout/html/setup.rb +89 -0
  77. data/templates/default/method/html/header.erb +17 -0
  78. data/templates/default/method/setup.rb +4 -0
  79. data/templates/default/method/text/header.erb +1 -0
  80. data/templates/default/method_details/html/header.erb +3 -0
  81. data/templates/default/method_details/html/method_signature.erb +25 -0
  82. data/templates/default/method_details/html/source.erb +10 -0
  83. data/templates/default/method_details/setup.rb +11 -0
  84. data/templates/default/method_details/text/header.erb +10 -0
  85. data/templates/default/method_details/text/method_signature.erb +12 -0
  86. data/templates/default/method_details/text/setup.rb +11 -0
  87. data/templates/default/module/dot/child.erb +1 -0
  88. data/templates/default/module/dot/dependencies.erb +3 -0
  89. data/templates/default/module/dot/header.erb +6 -0
  90. data/templates/default/module/dot/info.erb +14 -0
  91. data/templates/default/module/dot/setup.rb +15 -0
  92. data/templates/default/module/html/attribute_details.erb +10 -0
  93. data/templates/default/module/html/attribute_summary.erb +8 -0
  94. data/templates/default/module/html/box_info.erb +43 -0
  95. data/templates/default/module/html/children.erb +8 -0
  96. data/templates/default/module/html/constant_summary.erb +17 -0
  97. data/templates/default/module/html/defines.erb +3 -0
  98. data/templates/default/module/html/header.erb +5 -0
  99. data/templates/default/module/html/inherited_attributes.erb +14 -0
  100. data/templates/default/module/html/inherited_constants.erb +8 -0
  101. data/templates/default/module/html/inherited_methods.erb +19 -0
  102. data/templates/default/module/html/item_summary.erb +40 -0
  103. data/templates/default/module/html/method_details_list.erb +9 -0
  104. data/templates/default/module/html/method_summary.erb +14 -0
  105. data/templates/default/module/html/methodmissing.erb +12 -0
  106. data/templates/default/module/html/pre_docstring.erb +1 -0
  107. data/templates/default/module/setup.rb +167 -0
  108. data/templates/default/module/text/children.erb +10 -0
  109. data/templates/default/module/text/class_meths_list.erb +8 -0
  110. data/templates/default/module/text/extends.erb +8 -0
  111. data/templates/default/module/text/header.erb +7 -0
  112. data/templates/default/module/text/includes.erb +8 -0
  113. data/templates/default/module/text/instance_meths_list.erb +8 -0
  114. data/templates/default/module/text/setup.rb +13 -0
  115. data/templates/default/onefile/html/files.erb +5 -0
  116. data/templates/default/onefile/html/headers.erb +6 -0
  117. data/templates/default/onefile/html/layout.erb +17 -0
  118. data/templates/default/onefile/html/readme.erb +3 -0
  119. data/templates/default/onefile/html/setup.rb +62 -0
  120. data/templates/default/root/dot/child.erb +3 -0
  121. data/templates/default/root/dot/setup.rb +6 -0
  122. data/templates/default/root/html/setup.rb +2 -0
  123. data/templates/default/tags/html/example.erb +11 -0
  124. data/templates/default/tags/html/index.erb +3 -0
  125. data/templates/default/tags/html/option.erb +24 -0
  126. data/templates/default/tags/html/overload.erb +14 -0
  127. data/templates/default/tags/html/see.erb +8 -0
  128. data/templates/default/tags/html/tag.erb +20 -0
  129. data/templates/default/tags/setup.rb +57 -0
  130. data/templates/default/tags/text/example.erb +12 -0
  131. data/templates/default/tags/text/index.erb +1 -0
  132. data/templates/default/tags/text/option.erb +20 -0
  133. data/templates/default/tags/text/overload.erb +19 -0
  134. data/templates/default/tags/text/see.erb +11 -0
  135. data/templates/default/tags/text/tag.erb +13 -0
  136. data/templates/guide/class/html/setup.rb +2 -0
  137. data/templates/guide/docstring/html/setup.rb +2 -0
  138. data/templates/guide/fulldoc/html/css/style.css +108 -0
  139. data/templates/guide/fulldoc/html/js/app.js +33 -0
  140. data/templates/guide/fulldoc/html/setup.rb +74 -0
  141. data/templates/guide/layout/html/layout.erb +81 -0
  142. data/templates/guide/layout/html/setup.rb +25 -0
  143. data/templates/guide/method/html/header.erb +18 -0
  144. data/templates/guide/method/html/setup.rb +22 -0
  145. data/templates/guide/module/html/header.erb +7 -0
  146. data/templates/guide/module/html/method_list.erb +5 -0
  147. data/templates/guide/module/html/setup.rb +27 -0
  148. data/templates/guide/onefile/html/files.erb +4 -0
  149. data/templates/guide/onefile/html/setup.rb +6 -0
  150. data/templates/guide/onefile/html/toc.erb +3 -0
  151. data/templates/guide/tags/html/setup.rb +9 -0
  152. metadata +151 -2
data/docs/WhatsNew.md ADDED
@@ -0,0 +1,1245 @@
1
+ # @title What's New?
2
+
3
+ # What's New in 0.8.x?
4
+
5
+ 1. **Directives (new behavioural tag syntax)** (0.8.0)
6
+ 2. **Added `--embed-mixin(s)` to embed mixins into class docs** (0.8.0)
7
+ 3. **Internationalization (I18n) support for translating docs** (0.8.0)
8
+ 4. **New C parser / handlers architecture** (0.8.0)
9
+ 5. **YARD will now warn if `@param` name not in method params** (0.8.0)
10
+ 6. **Added support for `module_function` calls in Ruby code** (0.8.0)
11
+ 7. **Greatly improved tag documentation using custom template** (0.8.0)
12
+ 8. **Tags can now contain '.' for namespacing** (0.8.0)
13
+ 9. **Added "frames" links for non-framed pages for better nav** (0.8.0)
14
+ 10. **Added Gemfile support to YARD server for local gem sets** (0.8.0)
15
+ 11. **Server now displays README on index route like static docs** (0.8.0)
16
+ 12. **Added line numbers to `yard stats --list-undoc --compact`** (0.8.0)
17
+ 13. **Single object db now default (multi-object db unsupported)** (0.8.0)
18
+ 14. **Added `--api` tag to generate documentation for API sets** (0.8.1)
19
+ 15. **Added `--non-transitive-tag` to disable transitive tag** (0.8.3)
20
+ 16. **Added `-B/--bind` to bind to a port in yard server** (0.8.4)
21
+ 17. **Added `asciidoc` markup type support** (0.8.6)
22
+ 18. **Added `yard markups` command to list available markup types** (0.8.6)
23
+ 19. **Added `yard display` command to display formatted objects** (0.8.6)
24
+ 20. **Added `--layout` to `yard display` command** (0.8.6.1)
25
+ 21. **Added `stats_options` for the rake task** (0.8.7.6)
26
+
27
+ ## Directives (new behavioural tag syntax) (0.8.0)
28
+
29
+ <p class="note">
30
+ The tags {tag:!macro}, {tag:!method}, {tag:!attribute}, {tag:!group},
31
+ {tag:!endgroup}, {tag:!scope} and {tag:!visibility} have been changed
32
+ from meta-data tags to directives. This means they should now be called
33
+ with the "@!" prefix instead of "@". Note however that for <strong>
34
+ backward compatibility</strong>, the old "@macro", "@method", etc.,
35
+ syntax for all of these tags will still work and is supported.
36
+ </p>
37
+
38
+ <p class="note">
39
+ Some <strong>backwards incompatible</strong> changes were made to {tag:!macro} syntax.
40
+ Please read this section carefully if you are using this tag.
41
+ </p>
42
+
43
+ YARD 0.8.0 adds a new tag syntax called "directives" using the `@!`
44
+ prefix. These directive tags can be used to modify parser state while
45
+ processing objects, or even create new objects on the fly. A plugin
46
+ API is available similar to tags, and directives should be registered
47
+ in the {YARD::Tags::Library} class using {YARD::Tags::Library.define_directive}.
48
+
49
+ To use a directive, simply call it the same way as any tag. Tag syntax
50
+ is documented in {file:docs/Tags.md}.
51
+
52
+ ### Notable features of directives
53
+
54
+ #### Directives do not need to be attached to object docstrings
55
+
56
+ Unlike meta-data tags which apply to created objects, directives
57
+ do not need to be attached to an object in order to be used. This
58
+ means you can have free-standing comments with directives, such as:
59
+
60
+ # @macro mymacro
61
+ # A new macro, not attached to any docstring
62
+
63
+ # ...other Ruby code here...
64
+
65
+ # Using the macro:
66
+ # @macro mymacro
67
+ def mymethod; end
68
+
69
+ You can do the same to define methods and attributes, as discussed
70
+ below.
71
+
72
+ #### `@!method` and `@!attribute` directives improved
73
+
74
+ The method and attribute directives can now be used to create multiple
75
+ objects in a single docstring. Previously a `@method` or `@attribute`
76
+ tag would only create one method per docstring. In 0.8.0, you could
77
+ attach multiple methods to the same block of Ruby source, such as:
78
+
79
+ # @!method foo(a, b, c)
80
+ # @!method bar(x, y, z)
81
+ # Docstring for code
82
+ some_ruby_source
83
+
84
+ The above creates #foo and #bar and the source listing for both will
85
+ be `some_ruby_source` with "Docstring for code" as the docstring.
86
+
87
+ The attribute directive can take advantage of this functionality as well.
88
+ Note that these directives also do not need to be attached to a line of
89
+ code to be recognized; they can be in free-standing comments if the
90
+ methods are defined dynamically and not associated with any code.
91
+
92
+ #### New `@!parse` directive to parse Ruby code
93
+
94
+ A new {tag:!parse} directive was added that allows a developer to have
95
+ YARD parse code that might not necessarily be parsable in its original
96
+ form. This is useful when using `instance_eval` and other dynamic
97
+ meta-programming techniques to define methods or perform functionality.
98
+ For instance, a common case of the "self.included" callback in module
99
+ to extend a module on a class might be in the form:
100
+
101
+ def self.included(mod)
102
+ mod.extend(self)
103
+ end
104
+
105
+ Unfortunately, this does not get picked up by YARD, but on the original
106
+ class, we can add:
107
+
108
+ class MyClass
109
+ # @!parse extend TheDynamicModule
110
+ include TheDynamicModule
111
+ end
112
+
113
+ YARD will then parse the code `extend TheDynamicModule` as if
114
+ it were in the source file.
115
+
116
+ You can also use this technique to register regular methods as
117
+ attributes, if you did not define them with `attr_*` methods:
118
+
119
+ def foo; @foo end
120
+ def foo=(v) @foo = v end
121
+
122
+ # Register them as methods:
123
+ # @!parse attr_accessor :foo
124
+
125
+ ### Backward incompatible changes to `@!macro` directive
126
+
127
+ Unfortunately, in order to create the new directives architecture,
128
+ some previously supported syntax in `@macro` tags are no longer supported.
129
+ Specifically, macros can no longer expand text on an entire docstring.
130
+ Instead, macros only expand the data that is indented inside of the tag
131
+ text.
132
+
133
+ This syntax is **no longer supported**:
134
+
135
+ # @macro mymacro
136
+ # Expanding text $1 $2 $3
137
+ property :a, :b, :c
138
+
139
+ In 0.7.0 to 0.7.5, the above would have created a method with the docstring
140
+ "Expanding text a b c". This will not work in 0.8.0. Instead, you must
141
+ indent all the macro expansion data so that it is part of the `@macro`
142
+ tag as follows:
143
+
144
+ # @!macro mymacro
145
+ # Expanding text $1 $2 $3
146
+ property :a, :b, :c
147
+
148
+ Note that we also use the recommended `@!macro` syntax, though `@macro`
149
+ is still supported.
150
+
151
+ ## Added `--embed-mixin(s)` to embed mixins into class docs (0.8.0)
152
+
153
+ Methods from mixins can now be embedded directly into the documentation
154
+ output for a class by using `--embed-mixin ModuleName`, or `--embed-mixins`
155
+ for all mixins. This enables a documentation writer to refactor methods
156
+ into modules without worrying about them showing up in separate files
157
+ in generated documentation. When mixin methods are embedded, they
158
+ show up in both the original module page and the pages of the classes
159
+ they are mixed into. A note is added to the method signature telling the
160
+ user where the method comes from.
161
+
162
+ The `--embed-mixin` command-line option can also take wildcard values
163
+ in order to match specific namespaces. For instance, you can embed
164
+ only mixins inside of a "Foo::Bar" namespace by doing:
165
+
166
+ !!!sh
167
+ $ yard doc --embed-mixin "Foo::Bar::*"
168
+
169
+ ## Internationalization (I18n) support for translating docs
170
+
171
+ YARD now ships with the beginnings of internationalization support
172
+ for translating documentation into multiple languages. The
173
+ `yard i18n` command now allows you to generate ".pot" and ultimately
174
+ ".po" files for translation with [gettext](http://www.gnu.org/software/gettext).
175
+
176
+ Note that this tool is a small step in the larger transition for
177
+ proper I18n support in YARD. We still have to add proper gettext
178
+ support to our templates for proper generation in multiple languages,
179
+ but this tool allows you to get started in translating your
180
+ documents. Improved I18n support will come throughout the 0.8.x series.
181
+
182
+ ## New C parser / handlers architecture (0.8.0)
183
+
184
+ The C parser was completely rewritten to take advantage of YARD's
185
+ parser and handler architecture. This means more YARD will be more robust
186
+ when parsing failures occur, tags and directives will now work consistently
187
+ across Ruby and CRuby files ({tag:!group} will now work, for instance),
188
+ and developers can now write custom handlers that target CRuby source files.
189
+
190
+ ## YARD will now warn if `@param` name not in method params (0.8.0)
191
+
192
+ YARD will now give you a warning if you use a `@param` tag in your
193
+ source but give an invalid parameter name. This should catch a lot of
194
+ common documentation errors and help keep your documentation consistent.
195
+
196
+ ## Added support for `module_function` calls in Ruby code (0.8.0)
197
+
198
+ The `module_function` command in Ruby is now supported in Ruby files.
199
+ It defines two separate methods, one class and one instance method,
200
+ both having the exact same docstring, and marks the instance method
201
+ as private.
202
+
203
+ ## Greatly improved tag documentation using custom template (0.8.0)
204
+
205
+ We have completely revamped the {docs/Tags.md} to include documentation
206
+ for each meta-data tag and directive with at least one useful example
207
+ for each one. This was done using template customization and extension
208
+ available within YARD.
209
+
210
+ ## Tags can now contain '.' for namespacing (0.8.0)
211
+
212
+ Prior to 0.8.0, tags could only contain alphanumeric characters and
213
+ underscore. YARD now allows the '.' character in tag names, and it
214
+ is now recommended for namespacing project-specific custom tags.
215
+ YARD has its own set of custom tags that are namespaced in this
216
+ way (using the "yard.tagname" namespace). The namespace recommendation
217
+ is to use "projectname.tagname", or "projectname.component.tagname".
218
+
219
+ ## Added "frames" links for non-framed pages for better nav (0.8.0)
220
+
221
+ Frames navigation has always had a "(no frames)" link to get rid
222
+ of the frameset. YARD 0.8.0 introduces a "(frames)" link on non-framed
223
+ pages to reverse this, allowing you to navigate between framed and
224
+ frameless pages seamlessly.
225
+
226
+ ## Added Gemfile support to YARD server for local gem sets (0.8.0)
227
+
228
+ The `yard server` command now supports `--gemfile` to serve gems
229
+ from a Gemfile.lock, instead of all system-wide gems.
230
+
231
+ ## Server now displays README on index route like static docs (0.8.0)
232
+
233
+ The `yard server` command will now behave like static docs regarding
234
+ the index action for a project, listing the README file if present
235
+ before displaying the alphabetic index. Note that the route for
236
+ the alphabetic index page has now moved to the explicit '/index' action.
237
+
238
+ ## Added line numbers to `yard stats --list-undoc --compact` (0.8.0)
239
+
240
+ Line numbers are now listed in the compact listing of undocumented objects
241
+ so that they can be more easily located in the files.
242
+
243
+ ## Single object db now default (multi-object db unsupported) (0.8.0)
244
+
245
+ YARD previously would split the .yardoc db into multiple marshal files
246
+ for load-time performance reasons if it grew past a specific number of
247
+ objects. This check is now disabled, and YARD will never automatically
248
+ switch to a multi-object DB. YARD will now always use the single object
249
+ db unless explicitly set with `--no-single-db`. If YARD is taking a
250
+ long time to load your .yardoc database, you can try using this
251
+ option to split your database into multiple files, but note that this
252
+ can cause problems with certain codebases (specifically, if you
253
+ have class methods using the same name as a module/class).
254
+
255
+ ## Added `--api` tag to generate documentation for API sets (0.8.1)
256
+
257
+ You can now use `yardoc --api APINAME` to generate documentation only
258
+ for objects with the `@api APINAME` tag (or any parent namespace objects,
259
+ since this tag is transitive). Multiple `--api` switches may be used to
260
+ generate documentation for multiple APIs together. The following generates
261
+ documentation for both the "public" and "developer" APIs, also including
262
+ any objects with undefined API (via `--no-api`):
263
+
264
+ $ yard doc --api public --api developer --no-api
265
+
266
+ Note that if you use `--api`, you must ensure that you also add `@api`
267
+ tags to your namespace objects (modules and classes), not just your methods.
268
+ If you do not want to do this, you can also include all objects with *no*
269
+ `@api` tag by using `--no-api` as shown above.
270
+
271
+ Remember that applying an `@api` tag to a class or module will apply it
272
+ to all children that do not have this tag already defined, so you can
273
+ declare an entire class public by applying it to the class itself. Note
274
+ also that these tags can be overridden by child elements if the tag is
275
+ re-applied to the individual object.
276
+
277
+ This feature is a simplified version of the more powerful `--query`
278
+ switch. The query to display the same API documentation as the
279
+ above example would be:
280
+
281
+ $ yard doc --query '!@api || @api.text =~ /^(public|private)$/'
282
+
283
+ But note that `--query` does not work when YARD is in "safe mode"
284
+ due to security concerns, whereas `--api` works in either mode.
285
+ This enables `--api` to function on remote documentation sites like
286
+ [rubydoc.info](http://rubydoc.info).
287
+
288
+ ## Added `--non-transitive-tag` to disable transitive tag (0.8.3)
289
+
290
+ You can now use `--non-transitive-tag` to disable transitivity on
291
+ tags that are defined as transitive by default. For instance, in
292
+ some cases you might not want the @api tag to apply to all methods
293
+ when you define it on a class. Only the class itself has a specific
294
+ @api tag. To do this, you can mark @api as non-transitive with:
295
+
296
+ $ yard doc --non-transitive-tag api --api some_api
297
+
298
+ Which will avoid classifying treating @api as a transitive tag
299
+ when parsing modules and classes.
300
+
301
+ ## Added `-B/--bind` to bind to a port in yard server (0.8.4)
302
+
303
+ You can now bind the `yard server` command to a given local port
304
+ with `yard server -B PORT` or `yard server --bind PORT`.
305
+
306
+ ## Added `asciidoc` markup type support (0.8.6)
307
+
308
+ Support for the AsciiDoc markup type is now introduced using the `asciidoc`
309
+ markup type (`yard doc -m asciidoc`). Requires the
310
+ [asciidoctor](http://rubygems.org/gems/asciidoctor) RubyGem library to be
311
+ installed before running YARD.
312
+
313
+ ## Added `yard markups` command to list available markup types (0.8.6)
314
+
315
+ You can now list all available markup types and their respective providers by
316
+ typing `yard markups`. This list also includes the file extensions used to
317
+ auto-identify markup types for extra files and READMEs. To use a markup in
318
+ the list, call `yard doc` with `-m MARKUP_TYPE`. To select a specific markup
319
+ provider library, pass the `-M PROVIDER_NAME` option.
320
+
321
+ ## Added `yard display` command to display formatted objects (0.8.6)
322
+
323
+ <p class="note">This feature requires the .yardoc registry to have already been
324
+ generated. To generate the registry, run <code>yard doc -n</code>.
325
+ </p>
326
+
327
+ You can now display a single object (or a list of objects) in the YARD registry
328
+ using the `yard display OBJECT ...` command. For example, to display the
329
+ `YARD::CodeObjects` module as text (the way it is displayed in `yri`), type:
330
+
331
+ $ yard display YARD::CodeObjects
332
+
333
+ You can also format individual objects as HTML. For example, you can format
334
+ the above object as HTML and pipe the contents into a file readable by a
335
+ web browser:
336
+
337
+ $ yard display -f html YARD::CodeObjects > codeobjects.html
338
+
339
+ Custom templating options from `yard doc` can also be used, see
340
+ `yard display --help` for more options.
341
+
342
+ ## Added `--layout` to `yard display` command (0.8.6.1)
343
+
344
+ The `yard display` command now accepts `--layout` to wrap content in a layout
345
+ template. Currently the `layout` and `onefile` layout templates are supported,
346
+ though any template can be used. If no parameter is specified, the layout will
347
+ default to the `layout` template. Example usage:
348
+
349
+ $ yard display --layout onefile -f html YARD::CodeObjects > codeobjects.html
350
+
351
+ The above generates a `codeobjects.html` file that is self-contained with
352
+ CSS stylesheets and JavaScript code. This is similar to calling
353
+ `yard doc --one-file` with only the YARD::CodeObjects object in the registry.
354
+
355
+ Note that even though this uses the onefile template, the README file will not
356
+ be auto-included the way it is with the `yard doc` command. To include the
357
+ README text at the top of the onefile template, pass the --readme switch:
358
+
359
+ $ yard display --layout onefile -f html --readme README.md OBJECT > out.html
360
+
361
+ # What's New in 0.7.x?
362
+
363
+ 1. **Macro support and detection of DSL methods** (0.7.0)
364
+ 2. **Inherited attributes now show in HTML output** (0.7.0)
365
+ 3. **The 'app' directory is now parsed by default** (0.7.0)
366
+ 4. **Added support for metadata (@title, @markup) in extra files/readmes** (0.7.0)
367
+ 5. **Added `yard list` command (alias for `yardoc --list`)** (0.7.0)
368
+ 6. **Added Git support in `yard diff`** (0.7.0)
369
+ 7. **Added `{include:file:FILENAME}` syntax** (0.7.0)
370
+ 8. **Added `{render:OBJECT}` syntax to embed object docs in extra files** (0.7.0)
371
+ 9. **Added improved templates API for custom CSS/JS/menus** (0.7.0)
372
+ 10. **Added Ruby markup type (`-m ruby`)** (0.7.0)
373
+ 11. **Added state tracking variables to Parser/Handler architecture** (0.7.0)
374
+ 12. **Added before/after callbacks to SourceParser** (0.7.0)
375
+ 13. **Can now use `--yardopts FILE` to specify a custom yardopts file** (0.7.0)
376
+ 14. **Added new `-t guide` template for guide based docs** (0.7.0)
377
+ 15. **Github Flavoured Markdown now works out-of-box** (0.7.4)
378
+ 16. **Added `-m textile_strict` and `-m pre` markup types** (0.7.4)
379
+ 17. **Reorganized markup types 'text' and 'none'** (0.7.4)
380
+ 18. **Add support for `rb_define_alias`** (0.7.4)
381
+
382
+ ## Macro support and detection of DSL methods (0.7.0)
383
+
384
+ YARD will now automatically detect class level method calls, similar to the
385
+ way it knows what an `attr_accessor` is. By simply adding documentation to
386
+ your class level declarations, YARD can automatically detect them as methods
387
+ or attributes in your class. Consider DataMapper's "property" declaration:
388
+
389
+ class Post
390
+ # @attribute
391
+ # @return [String] the title of the post
392
+ property :title, String
393
+ end
394
+
395
+ The above declaration would be created as the `Post#title`. The optional
396
+ `@attribute` tag tells YARD that the property is an "attribute", and not just
397
+ a regular method.
398
+
399
+ In addition to basic DSL method detection, YARD also supports macros to create
400
+ docstrings that can be copies to other objects; these macros can also be
401
+ "attached" to class level methods to create implicit documentation for macros.
402
+
403
+ Macros and DSL method detection are discussed in much more detail in the
404
+ {file:docs/GettingStarted.md}, so you should read about them there if you're
405
+ interested in this feature.
406
+
407
+ ## Inherited attributes now show in HTML output (0.7.0)
408
+
409
+ Inherited attributes will now show up in HTML documentation using the default
410
+ template in the same manner that inherited methods do.
411
+
412
+ ## The 'app' directory is now parsed by default (0.7.0)
413
+
414
+ YARD tries to follow the "It Just Works" attitude in writing developer tools,
415
+ and therefore has added `app/**/*.rb` to the default list of globs that it
416
+ searches for code in. You no longer need to create a `.yardopts` just to
417
+ list your app directory when documenting your code on rubydoc.info.
418
+ We should have done this a while ago! And don't worry, YARD still checks
419
+ lib and ext by default, too.
420
+
421
+ ## Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)
422
+
423
+ Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now support
424
+ metadata tags, just like docstrings in code comments. By adding @tag values
425
+ to the top of a file (no whitespace preceding it) inside of a `# comment` line,
426
+ YARD will detect and parse these tags and store it for later usage.
427
+
428
+ Tags can contain arbitrary data as well as arbitrary tag names, however the
429
+ tag names @title and @markup are reserved to specify the document title and
430
+ markup format respectively. The title will be used in the file list menu,
431
+ index page, as well as any linking of the file via the `{file:Filename}`
432
+ syntax. An example of a document with metadata would be:
433
+
434
+ # @title The Best Project Ever!
435
+ # @markup rdoc
436
+ # @author Foo Bar (custom tag, does not display in templates)
437
+
438
+ = This Project Rules
439
+
440
+ == Contents
441
+
442
+ ...
443
+
444
+ Note that previous versions of YARD recommended specifying the markup of an
445
+ extra file with the `#!markup` shebang, but the `@markup` metadata tag is now
446
+ the "best practice" for specifying the markup format of an extra file.
447
+
448
+ ## Added `yard list` command (alias for `yardoc --list`) (0.7.0)
449
+
450
+ The `yardoc --list` command is used to list objects that are parsed from
451
+ a codebase. This can be used to grep methods/classes in a codebase from the
452
+ command line. `yard list` now calls `yardoc --list` as a convenience command.
453
+
454
+ Note that the `yardoc --list` command may eventually be replaced by a more
455
+ feature-filled `yard list` command, so `yard list` should be used instead of
456
+ `yardoc --list` when possible.
457
+
458
+ ## Added Git support in `yard diff` (0.7.0)
459
+
460
+ The `yard diff` command can now perform object diffing on git repositories.
461
+ Provide the `--git` switch to `yard diff` with 2 commit/branches like so:
462
+
463
+ $ yard diff --git HEAD~5 HEAD
464
+ Added objects:
465
+
466
+ YARD::Parser::SourceParser#contents
467
+ YARD::Parser::SourceParser#globals
468
+ ...
469
+
470
+ ## Added `{include:file:FILENAME}` syntax (0.7.0)
471
+
472
+ You can now use the `{include:file:FILENAME}` syntax to embed the contents
473
+ of an extra file marked up in its markup format. This syntax supports embedding
474
+ Ruby source files and performing syntax highlighting on the code.
475
+
476
+ ## Added `{render:OBJECT}` syntax to embed object docs in extra files (0.7.0)
477
+
478
+ You can now use the `{render:Object}` syntax to embed the documentation
479
+ rendering of an entire object (method, class, module) inside of an extra file.
480
+ This is useful when writing non-API based guides that might require listing
481
+ a few helper methods or classes. The {file:docs/GettingStarted.md} discussed
482
+ this syntax in more detail (with example usage).
483
+
484
+ ## Added improved templates API for custom CSS/JS/menus (0.7.0)
485
+
486
+ Plugin & template developers can now more easily insert custom stylesheet
487
+ or JavaScript files in their customized templates, thanks to an abstraction
488
+ of the template API. This is documented in the {docs/Templates.md} document.
489
+ In addition to custom CSS/JS, developers can also create custom menu tabs
490
+ in both the framed and non framed version of the default theme.
491
+
492
+ ## Added Ruby markup type (`-m ruby`) (0.7.0)
493
+
494
+ The Ruby markup type (`-m ruby`) will now use syntax highlighting for all
495
+ formatting. This is probably not useful as a global switch, but can be used
496
+ on individual extra files using the metadata markup specification discussed
497
+ above.
498
+
499
+ ## Added state tracking variables to Parser/Handler architecture (0.7.0)
500
+
501
+ The parser and handler architecture now contain state variables
502
+ {YARD::Handlers::Base#extra_state} and {YARD::Handlers::Processor#globals}
503
+ to share data across handlers and the entire processing phase. `#extra_state`
504
+ provided a place to store per-file data, while `#globals` gives the developer
505
+ access to inter-file state when parsing multiple files at once.
506
+
507
+ ## Added before/after callbacks to SourceParser (0.7.0)
508
+
509
+ The {YARD::Parser::SourceParser} class can now register callbacks to execute
510
+ code before and after parsing of file globs, as well as before and after
511
+ parsing of individual files. This allows plugin developers to perform
512
+ setup/teardown (and set global state or update the {YARD::Registry}).
513
+
514
+ See the documentation for the following methods:
515
+
516
+ * {YARD::Parser::SourceParser.before_parse_list}
517
+ * {YARD::Parser::SourceParser.after_parse_list}
518
+ * {YARD::Parser::SourceParser.before_parse_file}
519
+ * {YARD::Parser::SourceParser.after_parse_file}
520
+
521
+ ## Can now use `--yardopts FILE` to specify a custom yardopts file (0.7.0)
522
+
523
+ The `yardoc` command now supports `--yardopts FILE` to specify custom .yardopts
524
+ options files. This is useful if you have multiple documentation sets, such
525
+ as a guide documentation set and an API documentation set.
526
+
527
+ ## Added new `-t guide` template for guide based docs (0.7.0)
528
+
529
+ You can now write guide style documentation using a new 'guide' template that
530
+ only generates documentation for extra files. You would use it in the form:
531
+
532
+ yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE
533
+
534
+ This creates the sections for the readme, a getting started, frequently asked
535
+ questions, trouble shooting and license page.
536
+
537
+ If you need to refer to class / method documentation, you can embed API documentation
538
+ using the `{render:Object}` tag discussed above.
539
+
540
+ ## Github Flavoured Markdown now works out-of-box (0.7.4)
541
+
542
+ Due to the growing popularity of Github-Flavoured-Markdown (GFM), YARD now uses
543
+ the Redcarpet library as the default Markdown formatting library with GFM fenced
544
+ code blocks enabled. This means that you can use fenced code blocks inside of
545
+ Markdown files with redcarpet installed without any extra code. Previously, users
546
+ who wanted GFM in their Markdown would have to specify `-m markdown -M redcarpet`,
547
+ but this is now the default behaviour for YARD.
548
+
549
+ Note that you can still specify language types in code blocks without GFM in YARD
550
+ by using the "!!!lang" prefix syntax. For example (plain means no markup):
551
+
552
+ !!!plain
553
+ !!!plain
554
+ Some code
555
+ block here.
556
+
557
+ The GFM version would be:
558
+
559
+ !!!plain
560
+ ```plain
561
+ Some code
562
+ block here.
563
+ ```
564
+
565
+ ## Added `-m textile_strict` and `-m pre` markup types (0.7.4)
566
+
567
+ A new "textile_strict" markup type was added which behaves exactly like "textile"
568
+ except it enables hard breaks, so newlines behave as line breaks in the HTML
569
+ (using `<br>` tags). This option is added for users who want the classic textile
570
+ behaviour.
571
+
572
+ ## Reorganized markup types 'text' and 'none' (0.7.4)
573
+
574
+ Due to the new pre markup type, the behaviour for text and none were slightly
575
+ reorganized to be more intuitive. The following behaviours now represent these
576
+ markup types:
577
+
578
+ * pre: Used to wrap text inside `<pre>` tags
579
+ * text: No formatting except for hard breaks (`<br>`) on newlines
580
+ * none: No formatting at all.
581
+
582
+ In all cases, HTML is escaped from input. If you want no HTML escaping, use the
583
+ html markup type.
584
+
585
+ ## Add support for `rb_define_alias` (0.7.4)
586
+
587
+ CRuby code can now make use of the `rb_define_alias` function. Documentation
588
+ for aliases is not supported, however.
589
+
590
+ # What's New in 0.6.x?
591
+
592
+ 1. **Local documentation server for RubyGems or projects (`yard server`)** (0.6.0)
593
+ 2. **Groups support for method listing** (0.6.0)
594
+ 3. **Single file template (`--one-file`) support** (0.6.0)
595
+ 4. **`yard` CLI executable with pluggable commands** (0.6.0)
596
+ 5. **`yard diff` command to object-diff two versions of a project** (0.6.0)
597
+ 6. **Added `--asset` option to `yardoc`** (0.6.0)
598
+ 7. **New template API** (0.6.0)
599
+ 8. **HTML template now adds inline Table of Contents for extra files pages** (0.6.0)
600
+ 9. **Removed `--incremental` in favour of `--use-cache`** (0.6.0)
601
+ 10. **Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.)** (0.6.0)
602
+ 11. **Added `--transitive-tags` to register transitive tags** (0.6.0)
603
+ 12. **`yardoc` now displays RDoc-like statistics (`--no-stats` to hide)** (0.6.0)
604
+ 13. **`yri` now works on constants** (0.6.0)
605
+ 14. **Plugins are no longer auto-loaded (added `--plugin` switch)** (0.6.2)
606
+ 15. **Added `YARD::Config` API and `~/.yard/config` configuration file** (0.6.2)
607
+ 16. **Added `yard config` command to view/edit configuration** (0.6.2)
608
+ 17. **Added `yard server -t` template path switch** (0.6.2)
609
+ 18. **Added `YARD::Server.register_static_path` for static server assets** (0.6.2)
610
+ 19. **YARD::Registry is now thread local** (0.6.5)
611
+ 20. **Support for ripper gem in Ruby 1.8.7** (0.6.5)
612
+
613
+ ## Local documentation server for RubyGems or projects (`yard server`) (0.6.0)
614
+
615
+ The new `yard server` command spawns a documentation server that can serve
616
+ either documentation for a local project or installed RubyGems. The server
617
+ will host (by default) on http://localhost:8808.
618
+
619
+ To serve documentation for the active project (in the current directory):
620
+
621
+ $ yard server
622
+
623
+ The server can also run in "incremental" mode for local projects. In this
624
+ situation, any modified sources will immediately be updated at each request,
625
+ ensuring that the server always serve the code exactly as it is on disk.
626
+ Documenting your code in this fashion essentially gives you an efficient a
627
+ live preview without running a separate command everytime you make a change.
628
+ To serve documentation for the active project in incremental mode:
629
+
630
+ $ yard server --reload
631
+
632
+ <span class="note">Note that in incremental mode, objects or method groupings
633
+ cannot be removed. If you have removed objects or modified groupings, you
634
+ will need to flush the cache by deleting `.yardoc` and (optionally)
635
+ restarting the server.</span>
636
+
637
+ The documentation server can also serve documentation for all installed gems
638
+ on your system, similar to `gem server`, but using YARD's functionality and
639
+ templates. To serve documentation for installed gems:
640
+
641
+ $ yard server --gems
642
+
643
+ <span class="note">Documentation for the gem need not be previously generated
644
+ at install-time. If documentation for the gem has not been generated, YARD
645
+ will do this for you on-the-fly. It is therefore possible to speed up your
646
+ gem installs by using `gem install GEMNAME --no-rdoc` without repercussion.
647
+ You can also add this switch to your `~/.gemrc` file so that you don't need
648
+ 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)
649
+ for exact instructions.</span>
650
+
651
+ ## Groups support for method listing (0.6.0)
652
+
653
+ You can now organize methods in a class/module into logical separated groups.
654
+ These groups apply lexically and are listed in the order they are defined.
655
+ For instance, to define a group:
656
+
657
+ # @group Rendering an Object
658
+
659
+ # Documentation here
660
+ def foo; end
661
+
662
+ # Extra documentation...
663
+ def bar; end
664
+
665
+ # @group Another Group
666
+
667
+ def aaa; end
668
+
669
+ <span class="note">Note that these `@group` and `@endgroup` declarations are
670
+ not "tags" and should always be separated with at least 1 line of whitespace
671
+ from any other documentation or code.</span>
672
+
673
+ In the above example, "Rendering an Object" will be listed with "foo" and
674
+ "bar" above "Another Group", even though "aaa" comes before the two other
675
+ methods, alphabetically. To end a group, use `@endgroup`. It is not necessary
676
+ to end a group to start a new one, only if there is an object following the
677
+ group that should not belong in any group.
678
+
679
+ # @group Group 1
680
+
681
+ def foo; end
682
+
683
+ # @endgroup
684
+
685
+ # This method should not be listed in any group
686
+ def bar; end
687
+
688
+ ## Single file template (`--one-file`) support (0.6.0)
689
+
690
+ `yardoc` now has the `--one-file` option to generate a single-file template
691
+ for small scripts and libraries. In this case, any comments at the top of
692
+ the script file will be recognized as a README.
693
+
694
+ ## `yard` CLI executable with pluggable commands (0.6.0)
695
+
696
+ <span class="note">The `yardoc` and `yri` commands are not deprecated and can
697
+ continue to be used. They are shortcuts for `yard doc` and `yard ri`
698
+ respectively. However, `yard-graph` has been removed.</span>
699
+
700
+ YARD now has a `yard` executable which combines all pre-existing and new
701
+ commands into a single pluggable command that is both easier to remember and
702
+ access. To get a list of commands, type `yard --help`.
703
+
704
+ If you are a plugin developer, you can create your own `yard` command by first
705
+ subclassing the {YARD::CLI::Command} class and then registering this class
706
+ with the {YARD::CLI::CommandParser.commands} list. For instance:
707
+
708
+ YARD::CLI::CommandParser.commands[:my_command] = MyCommandClass
709
+
710
+ The above line will enable the user to execute `yard my_command [options]`.
711
+
712
+ ## `yard diff` command to object-diff two versions of a project (0.6.0)
713
+
714
+ One of the built-in commands that comes with the new `yard` executable is the
715
+ ability to do object-oriented diffing across multiple versions of the same
716
+ project, either by 2 versions of a gem, or 2 working copies. Just like
717
+ regular diffing tells you which lines have been added/removed in a file,
718
+ object diffing allows you to see what classes/methods/modules have been
719
+ added/removed between versions of a codebase.
720
+
721
+ For an overview of how to use `yard diff`, see [YARD Object Oriented Diffing](http://gnuu.org/2010/06/26/yard-object-oriented-diffing/).
722
+
723
+ ## `yard stats` to display statistics and undocumented objects (0.6.0)
724
+
725
+ YARD now outputs the following statistics when `yard stats` is run:
726
+
727
+ Files: 125
728
+ Modules: 35 ( 4 undocumented)
729
+ Classes: 139 ( 29 undocumented)
730
+ Constants: 53 ( 20 undocumented)
731
+ Methods: 602 ( 70 undocumented)
732
+ 85.16% documented
733
+
734
+ Note that these statistics are based on what you have set to show in your
735
+ documentation. If you use `@private` tags and/or do not display
736
+ private/protected methods in your documentation, these will not show up as
737
+ undocumented. Therefore this metric is contextual.
738
+
739
+ You can also specifically list all undocumented objects (and their file
740
+ locations) with the `--list-undoc` option.
741
+
742
+ ## Added `--asset` option to `yardoc` (0.6.0)
743
+
744
+ The `yardoc` command can now take the `--asset` option to copy over
745
+ files/directories (recursively) to the output path after generating
746
+ documentation. The format of the argument is "from:to" where from is the
747
+ source path and to is the destination. For instance, YARD uses the following
748
+ syntax in the `.yardopts` file to copy over image assets from the
749
+ 'docs/images' directory into the 'images' directory after generating HTML:
750
+
751
+ --asset docs/images:images
752
+
753
+ ## New template API (0.6.0)
754
+
755
+ The new template API allows for easier insertion of sections within an
756
+ inherited template. You should no longer need to insert by index, an
757
+ error-prone process that could break when a template is updated. Instead of:
758
+
759
+ sections.last.place(:my_section).before(:another_section)
760
+
761
+ use:
762
+
763
+ sections.place(:my_section).before_any(:another_section)
764
+
765
+ You can see more in the {file:docs/Templates.md#Inserting_and_Traversing_Sections}
766
+ document.
767
+
768
+ ## HTML template now adds inline Table of Contents for extra files pages (0.6.0)
769
+
770
+ A table of contents is now generated dynamically using JavaScript for extra
771
+ file pages (such as README's, or this document). It is generated based off the
772
+ headers (h1,h2,... tags) used in the document, and can be floated to the
773
+ right or listed inline on the page.
774
+
775
+ ## Ad-hoc tag registration via `yardoc` CLI (`--tag`, etc.) (0.6.0)
776
+
777
+ Simple meta-data tags can now be added at the command-line and registered to
778
+ display in templates in a number of pre-defined ways. For instance, to create
779
+ a freeform text tag, use the following:
780
+
781
+ --tag my_tag_name:"My Tag Title"
782
+
783
+ You can also create a "typed" tag (similar to `@return`), a typed named tag
784
+ (similar to `@param`) as well as various combinations. The full list of
785
+ options are listed in `yardoc --help` under the "Tag Options" section.
786
+
787
+ If you wish to create a tag to store data but do not wish to show this data
788
+ in the templates, use the `--hide-tag` option to hide it from generated output:
789
+
790
+ --hide-tag my_tag_name
791
+
792
+ ## Added `--transitive-tags` to register transitive tags (0.6.0)
793
+
794
+ Transitive tags are tags that apply to all descendants of a namespace (class
795
+ or module) when documented on that namespace. For instance, the `@since` tag
796
+ is a transitive tag. Applying `@since` to a class will automatically apply
797
+ `@since` to all methods in the class. Creating a `@since` tag directly on a
798
+ method will override the inherited value.
799
+
800
+ You can specify transitive tags on the command-line by using this option. Note
801
+ that the tags must already exist (built-in or created with the `--tag` option)
802
+ to be specified as transitive. If you wish to do this programmatically, see
803
+ the {YARD::Tags::Library.transitive_tags} attribute.
804
+
805
+ ## `yardoc` now displays RDoc-like statistics (`--no-stats` to hide) (0.6.0)
806
+
807
+ As seen in the `yard stats` feature overview, `yardoc` displays RDoc-like
808
+ statistics when it is run. The output is equivalent to typing `yard stats`.
809
+ To hide this output when yardoc is run, use `--no-stats`.
810
+
811
+ ## `yri` now works on constants (0.6.0)
812
+
813
+ Templates have now been added for text view of constants, which displays any
814
+ documentation and the constant value.
815
+
816
+ ## Plugins are no longer auto-loaded (added `--plugin` switch) (0.6.2)
817
+
818
+ This is a backwards-incompatible change that disables plugins from automatically
819
+ loading when YARD starts up. From now on, you should manually declare which
820
+ plugins your project is using by adding `--plugin PLUGINNAME` to a `.yardopts`
821
+ file in the root of your project. You can also re-enable autoloaded plugins
822
+ by setting `load_plugins` to true in your configuration file (`yard config load_plugins true`,
823
+ see next item). You can also set `autoload_plugins` to a list of plugins
824
+ to be automatically loaded on start.
825
+
826
+ If you are a YARD plugin author, please make sure to inform your users of these
827
+ changes.
828
+
829
+ Note that `--plugin` switches passed on the commandline (not via `.yardopts`)
830
+ are parsed before commands are loaded, and therefore can add in new CLI commands.
831
+
832
+ ## Added `YARD::Config` API and `~/.yard/config` configuration file (0.6.2)
833
+
834
+ There is a new global configuration API that can be accessed programmatically
835
+ and set via the `~/.yard/config` file. The file is encoded as a YAML file,
836
+ and looks like:
837
+
838
+ :load_plugins: false
839
+ :ignored_plugins:
840
+ - my_plugin
841
+ - my_other_plugin
842
+ :autoload_plugins:
843
+ - my_autoload_plugin
844
+ :safe_mode: false
845
+
846
+ You can also set configuration options via the command-line (see next item).
847
+
848
+ ## Added `yard config` command to view/edit configuration (0.6.2)
849
+
850
+ A new `yard config` command was created to view or edit the configuration
851
+ file via the commandline.
852
+
853
+ * To view the current configuration use `yard config --list`.
854
+ * To view a specific item use `yard config ITEMNAME`
855
+ * To modify an item value use `yard config ITEMNAME VALUE`
856
+
857
+ ## Added `yard server -t` template path switch (0.6.2)
858
+
859
+ The `yard server` command now accepts `-t` or `--template-path` to register
860
+ a new template path for template customization.
861
+
862
+ ## Added `YARD::Server.register_static_path` for static server assets (0.6.2)
863
+
864
+ The server now supports a command to register static asset paths. If you are
865
+ extending the YARD::Server modules, make sure to register your asset paths
866
+ through this method.
867
+
868
+ ## YARD::Registry is now thread local (0.6.5)
869
+
870
+ Creating a new thread will now implicitly load a new Registry that can be used
871
+ to parse and process new code objects independently of the other threads. Note
872
+ that this means you can no longer use the Registry across threads; you must
873
+ either access the threadlocal object directly, or synchronize threads to do
874
+ the processing in the initial registry's thread.
875
+
876
+ ## Support for ripper gem in Ruby 1.8.7 (0.6.5)
877
+
878
+ YARD now supports the Ruby 1.8.7 port of the `ripper` gem to improve parsing
879
+ of source, both in terms of performance and functionality. When the `ripper`
880
+ gem is available, YARD will use the "new-style" handlers. You can take advantage
881
+ of this functionality by performing a `gem install ripper`.
882
+
883
+
884
+ What's New in 0.5.x?
885
+ ====================
886
+
887
+ 1. **Support for documenting native Ruby C code** (0.5.0)
888
+ 2. **Incremental parsing and output generation with `yardoc -c`** (0.5.0, 0.5.3)
889
+ 2. **Improved `yri` support to perform lookups on installed Gems** (0.5.0)
890
+ 3. **Added `yardoc --default-return` and `yardoc --hide-void-return`** (0.5.0)
891
+ 4. **Multiple syntax highlighting language support** (0.5.0)
892
+ 5. **New .yardoc format** (0.5.0)
893
+ 6. **Support for yard-doc-* gem packages as hosted .yardoc dbs** (0.5.1)
894
+ 7. **Support for extra search paths in `yri`** (0.5.1)
895
+ 8. **Generating HTML docs now adds frames view** (0.5.3)
896
+ 9. **Tree view for class list** (0.5.3)
897
+ 10. **Ability to specify markup format of extra files** (0.5.3)
898
+ 11. **Keyboard shortcuts for default HTML template** (0.5.4)
899
+
900
+ Support for documenting native Ruby C code (0.5.0)
901
+ --------------------------------------------------
902
+
903
+ It is now possible to document native Ruby extensions with YARD with a new
904
+ C parser mostly borrowed from RDoc. This enables the ability to document
905
+ Ruby's core and stdlibs which will be hosted on http://yardoc.org/docs. In
906
+ addition, the .yardoc dump for the Ruby-core classes will become available
907
+ as an installable gem for yri support (see #3).
908
+
909
+ Incremental parsing and output generation with `yardoc -c` (0.5.0, 0.5.3)
910
+ -------------------------------------------------------------------------
911
+
912
+ <p class="note">Note: in 0.5.3 and above you must use <tt>--incremental</tt>
913
+ to incrementally generate HTML, otherwise only parsing will be done
914
+ incrementally but HTML will be generated with all objects. <tt>--incremental</tt>
915
+ implies <tt>-c</tt>, so no need to specify them both.</p>
916
+
917
+ YARD now compares file checksums before parsing when using `yardoc -c`
918
+ (aka `yardoc --use-cache`) to do incremental parsing of only the files that
919
+ have changed. HTML (or other output format) generation will also only be
920
+ done on the objects that were parsed from changed files (\*). This makes doing
921
+ a documentation development cycle much faster for quick HTML previews. Just
922
+ remember that when using incremental output generation, the index will not
923
+ be rebuilt and inter-file links might not hook up right, so it is best to
924
+ perform a full rebuild at the end of such previews.
925
+
926
+ (\*) Only for versions prior to 0.5.3. For 0.5.3+, use `--incremental` for
927
+ incremental HTML output.
928
+
929
+ Improved `yri` support to perform lookups on installed Gems (0.5.0)
930
+ -------------------------------------------------------------------
931
+
932
+ The `yri` executable can now perform lookups on gems that have been parsed
933
+ by yard. Therefore, to use this command you must first parse all gems with
934
+ YARD. To parse all gems, use the following command:
935
+
936
+ $ sudo yardoc --build-gems
937
+
938
+ The above command builds a .yardoc file for all installed gems in the
939
+ respective gem directory. If you do not have write access to the gem path,
940
+ YARD will write the yardoc file to `~/.yard/gem_index/NAME-VERSION.yardoc`.
941
+
942
+ Note: you can also use `--re-build-gems` to force re-parsing of all gems.
943
+
944
+ You can now do lookups with yri:
945
+
946
+ $ yri JSON
947
+
948
+ All lookups are cached to `~/.yard/yri_cache` for quicker lookups the second
949
+ time onward.
950
+
951
+ Added `yardoc --default-return` and `yardoc --hide-void-return` (0.5.0)
952
+ -----------------------------------------------------------------------
953
+
954
+ YARD defaults to displaying (Object) as the default return type of any
955
+ method that has not declared a @return tag. To customize the default
956
+ return type, you can specify:
957
+
958
+ $ yardoc --default-return 'MyDefaultType'
959
+
960
+ You can also use the empty string to list no return type.
961
+
962
+ In addition, you can use --hide-void-return to ignore any method that
963
+ defines itself as a void type by: `@return [void]`
964
+
965
+ Multiple syntax highlighting language support (0.5.0)
966
+ -----------------------------------------------------
967
+
968
+ YARD now supports the ability to specify a language type for code blocks in
969
+ docstrings. Although no actual highlighting support is added for any language
970
+ but Ruby, you can add your own support by writing your own helper method:
971
+
972
+ # Where LANGNAME is the language:
973
+ def html_syntax_highlight_LANGNAME(source)
974
+ # return highlighted HTML
975
+ end
976
+
977
+ To use this language in code blocks, prefix the block with `!!!LANGNAME`:
978
+
979
+ !!!plain
980
+ !!!python
981
+ def python_code(self):
982
+ return self
983
+
984
+ By the same token. you can now use `!!!plain` to ignore highlighting for
985
+ a specific code block.
986
+
987
+ New .yardoc format (0.5.0)
988
+ --------------------------
989
+
990
+ To make the above yri support possible, the .yardoc format was redesigned
991
+ to be a directory instead of a file. YARD can still load old .yardoc files,
992
+ but they will be automatically upgraded if re-saved. The new .yardoc format
993
+ does have a larger memory footprint, but this will hopefully be optimized
994
+ downward.
995
+
996
+ Support for yard-doc-* gem packages as hosted .yardoc dbs (0.5.1)
997
+ -----------------------------------------------------------------
998
+
999
+ You can now install special YARD plugin gems titled yard-doc-NAME to get
1000
+ packaged a .yardoc database. This will enable yri lookups or building docs
1001
+ for the gem without the code.
1002
+
1003
+ One main use for this is the `yard-doc-core` package, which enabled yri
1004
+ support for Ruby core classes (stdlib coming soon as `yard-doc-stdlib`).
1005
+ To install it, simply:
1006
+
1007
+ $ sudo gem install yard-doc-core
1008
+ # now you can use:
1009
+ $ yri String
1010
+
1011
+ This will by default install the 1.9.1 core library. To install a library
1012
+ for a specific version of Ruby, use the `--version` switch on gem:
1013
+
1014
+ $ sudo gem install --version '= 1.8.6' yard-doc-core
1015
+
1016
+ Support for extra search paths in `yri` (0.5.1)
1017
+ -----------------------------------------------
1018
+
1019
+ You can now add custom paths to non-gem .yardoc files
1020
+ by adding them as newline separated paths in `~/.yard/yri_search_paths`.
1021
+
1022
+ Generating HTML docs now adds frames view (0.5.3)
1023
+ -------------------------------------------------
1024
+
1025
+ `yardoc` will now create a `frames.html` file when generating HTML documents
1026
+ which allows the user to view documentation inside frames, for those users who
1027
+ still find frames beneficial.
1028
+
1029
+ Tree view for class list (0.5.3)
1030
+ --------------------------------
1031
+
1032
+ The class list now displays as an expandable tree view to better organized an
1033
+ otherwise cluttered namespace. If you properly namespace your less important
1034
+ classes (like Rails timezone classes), they will not take up space in the
1035
+ class list unless the user looks for them.
1036
+
1037
+ Ability to specify markup format of extra files (0.5.3)
1038
+ -------------------------------------------------------
1039
+
1040
+ You can now specify the markup format of an extra file (like README) at the
1041
+ top of the file with a shebang-like line:
1042
+
1043
+ #!textile
1044
+ contents here
1045
+
1046
+ The above file contents will be rendered with a textile markup engine
1047
+ (eg. RedCloth).
1048
+
1049
+ Keyboard shortcuts for default HTML template (0.5.4)
1050
+ ----------------------------------------------------
1051
+
1052
+ You can now access the "Class List", "Method List" and "File List" with the
1053
+ 'c', 'm' and 'f' keyboard shortcuts in the default HTML template, allowing
1054
+ for keyboard-only navigation around YARD documentation.
1055
+
1056
+ API for registering custom parsers (0.5.6)
1057
+ ------------------------------------------
1058
+
1059
+ You can now register parsers for custom source languages by calling the
1060
+ following method:
1061
+
1062
+ SourceParser.register_parser_type(:java, MyJavaParser, 'java')
1063
+
1064
+ The parser class MyJavaParser should be a subclass of {YARD::Parser::Base},
1065
+ and the last argument is a set of extensions (string, array or regexp). You
1066
+ can read more about registering parsers at the {YARD::Parser::SourceParser}
1067
+ class documentation.
1068
+
1069
+
1070
+ What's New in 0.4.x?
1071
+ ====================
1072
+
1073
+ 1. **New templating engine and templates**
1074
+ 2. **yardoc `--query` argument**
1075
+ 3. **Greatly expanded API documentation**
1076
+ 4. **New plugin support**
1077
+ 5. **New tags (@abstract, @private)**
1078
+ 6. **Default rake task is now `rake yard`**
1079
+
1080
+ New templating engine and templates
1081
+ -----------------------------------
1082
+
1083
+ The templates were redesigned, most notably removing the ugly frameset, adding
1084
+ search to the class/method lists, simplifying the layout and making things
1085
+ generally prettier. You should also notice that more tags are now visible in
1086
+ the templates such as @todo, the new @abstract and @note tags and some others
1087
+ that existed but were previously omitted from the generated documentation.
1088
+
1089
+ There is also a new templating engine (based on the tadpole templating library)
1090
+ to allow for much more user customization. You can read about it in
1091
+ {file:docs/Templates.md}.
1092
+
1093
+ yardoc `--query` argument
1094
+ -------------------------
1095
+
1096
+ The yardoc command-line tool now supports queries to select which classes,
1097
+ modules or methods to include in documentation based on their data or meta-data.
1098
+ For instance, you can now generate documentation for your "public" API only by
1099
+ adding "@api public" to each of your public API methods/classes and using
1100
+ the following argument:
1101
+
1102
+ --query '@api.text == "public"'
1103
+
1104
+ More information on queries is in the {file:README.md}.
1105
+
1106
+ Greatly expanded API documentation
1107
+ ----------------------------------
1108
+
1109
+ Last release focused on many how-to and architecture documents to explain
1110
+ the design of YARD, but many of the actual API classes/methods were still
1111
+ left undocumented. This release marks a focus on getting YARD's own documentation
1112
+ up to par so that it can serve as an official reference on the recommended
1113
+ conventions to use when documenting code.
1114
+
1115
+ New plugin support
1116
+ ------------------
1117
+
1118
+ YARD now supports loading of plugins via RubyGems. Any gem named `yard-*` or
1119
+ `yard_*` will now be loaded when YARD starts up. Note that the '-' separator
1120
+ is the recommended naming scheme.
1121
+
1122
+ To ignore plugins, add the gem names to `~/.yard/ignored_plugins` on separate
1123
+ lines (or separated by whitespace).
1124
+
1125
+ New tags (@abstract, @private)
1126
+ ------------------------------
1127
+
1128
+ Two new tags were added to the list of builtin meta-tags in YARD. `@abstract`
1129
+ marks a class/module/method as abstract while `@private` marks an object
1130
+ as "private". The latter tag is used in situations where an object is public
1131
+ due to Ruby's own visibility limitations (constants, classes and modules
1132
+ can never be private) but not actually part of your public API. You should
1133
+ use this tag sparingly, as it is not meant to be an equivalent to RDoc's
1134
+ `:nodoc:` tag. Remember, YARD recommends documenting private objects too.
1135
+ This tag exists so that you can create a query (`--query !@private`) to
1136
+ ignore all of these private objects in your documentation. You can also
1137
+ use the new `--no-private` switch, which is a shortcut to the aforementioned
1138
+ query. You can read more about the new tags in the {file:docs/GettingStarted.md}
1139
+ guide.
1140
+
1141
+ Default rake task is now `rake yard`
1142
+ ------------------------------------
1143
+
1144
+ Not a big change, but anyone using the default "rake yardoc" task should
1145
+ update their scripts:
1146
+
1147
+ [http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0](http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0)
1148
+
1149
+
1150
+ What's New in 0.2.3.x?
1151
+ ======================
1152
+
1153
+ 1. **Full Ruby 1.9 support**
1154
+ 2. **New parser code and handler API for 1.9**
1155
+ 3. **A new `@overload` tag**
1156
+ 4. **Better documentation**
1157
+ 5. **Template changes and bug fixes**
1158
+
1159
+ Full Ruby 1.9 support
1160
+ ---------------------
1161
+
1162
+ YARD's development actually focuses primarily on 1.9 from the get-go, so it is
1163
+ not an afterthought. All features are first implemented for compatibility with
1164
+ 1.9, but of course all functionality is also tested in 1.8.x. YARD 0.2.2 was
1165
+ mostly compatible with 1.9, but the new release improves and extends in certain
1166
+ areas where compatibility was lacking. The new release should be fully functional
1167
+ in Ruby 1.9.
1168
+
1169
+ New parser code and handler API for 1.9
1170
+ ---------------------------------------
1171
+
1172
+ Using Ruby 1.9 also gives YARD the advantage of using the new `ripper` library
1173
+ which was added to stdlib. The ripper parser is Ruby's official answer to
1174
+ projects like ParseTree and ruby2ruby. Ripper allows access to the AST as it
1175
+ is parsed by the Ruby compiler. This has some large benefits over alternative
1176
+ projects:
1177
+
1178
+ 1. It is officially supported and maintained by the Ruby core team.
1179
+ 2. The AST is generated directly from the exact same code that drives the
1180
+ compiler, meaning anything that compiles is guaranteed to generate the
1181
+ equivalent AST.
1182
+ 3. It needs no hacks, gems or extra libs and works out of the box in 1.9.
1183
+ 4. It's *fast*.
1184
+
1185
+ Having the AST means that developers looking to extend YARD have much better
1186
+ access to the parsed code than in previous versions. The only caveat is that
1187
+ this library is not back-compatible to 1.8.x. Because of this, there are
1188
+ subtle changes to the handler extension API that developers use to extend YARD.
1189
+ Namely, there is now a standard API for 1.9 and a "legacy" API that can run in
1190
+ both 1.8.x and 1.9 if needed. A developer can still use the legacy API to write
1191
+ handlers that are compatible for both 1.8.x and 1.9 in one shot, or decide to
1192
+ implement the handler using both APIs. Realize that the benefit of using the new
1193
+ API means 1.9 users will get a 2.5x parsing speed increase over running the legacy
1194
+ handlers (this is *in addition to* the ~1.8x speed increase of using YARV over MRI).
1195
+
1196
+ A new `@overload` tag
1197
+ ---------------------
1198
+
1199
+ The new `@overload` tag enables users to document methods that take multiple
1200
+ parameters depending on context. This is basically equivalent to RDoc's call-seq,
1201
+ but with a name that is more akin to the OOP concept of method overloading
1202
+ that is actually being employed. Here's an example:
1203
+
1204
+ # @overload def to_html(html, autolink = true)
1205
+ # This docstring describes the specific overload only.
1206
+ # @param [String] html the HTML
1207
+ # @param [Boolean] autolink whether or not to automatically link
1208
+ # URL references
1209
+ # @overload def to_html(html, opts = {})
1210
+ # @param [String] html the HTML
1211
+ # @param [Hash] opts any attributes to add to the root HTML node
1212
+ def to_html(*args)
1213
+ # split args depending on context
1214
+ end
1215
+
1216
+ As you can see each overload takes its own nested tags (including a docstring)
1217
+ as if it were its own method. This allows "virtual" overloading behaviour at
1218
+ the API level to make Ruby look like overload-aware languages without caring
1219
+ about the implementation details required to add the behaviour.
1220
+
1221
+ It is still recommended practice, however, to stay away from overloading when
1222
+ possible and document the types of each method's real parameters. This allows
1223
+ toolkits making use of YARD to get accurate type information for your methods,
1224
+ for instance, allowing IDE autocompletion. There are, of course, situations
1225
+ where overload just makes more sense.
1226
+
1227
+ Better documentation
1228
+ --------------------
1229
+
1230
+ The first few iterations of YARD were very much a proof of concept. Few people
1231
+ were paying attention and it was really just pieced together to see what was
1232
+ feasible. Now that YARD is gaining interest, there are many developers that
1233
+ want to take advantage of its extensibility support to do some really cool stuff.
1234
+ Considerable time was spent for this release documenting, at a high level, what
1235
+ YARD can do and how it can be done. Expect this documentation to be extended and
1236
+ improved in future releases.
1237
+
1238
+ Template changes and bug fixes
1239
+ ------------------------------
1240
+
1241
+ Of course no new release would be complete without fixing the old broken code.
1242
+ Some tags existed but were not present in generated documentation. The templates
1243
+ were mostly fixed to add the major omitted tags. In addition to template adjustments,
1244
+ many parsing bugs were ironed out to make YARD much more stable with existing projects
1245
+ (Rails, HAML, Sinatra, Ramaze, etc.).