Skip to content
Newer
Older
100644 355 lines (266 sloc) 14.8 KB
7afd7e9 @lsegal Update README formatting
authored
1 YARD: Yay! A Ruby Documentation Tool
2 ====================================
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
3
61e6769 @lsegal Bump version to 0.5.5
authored
4 **Homepage**: [http://yardoc.org](http://yardoc.org)
7afd7e9 @lsegal Update README formatting
authored
5 **IRC**: [irc://irc.freenode.net/yard](irc.freenode.net / #yard)
61e6769 @lsegal Bump version to 0.5.5
authored
6 **Git**: [http://github.com/lsegal/yard](http://github.com/lsegal/yard)
7 **Author**: Loren Segal
2e95dd9 @lsegal Bump to version 0.5.8
authored
8 **Contributors**: See Contributors section below
61e6769 @lsegal Bump version to 0.5.5
authored
9 **Copyright**: 2007-2010
10 **License**: MIT License
2e95dd9 @lsegal Bump to version 0.5.8
authored
11 **Latest Version**: 0.5.8 (codename "The Longest")
12 **Release Date**: June 22nd 2010
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
13
7afd7e9 @lsegal Update README formatting
authored
14 Synopsis
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
15 --------
16
17 YARD is a documentation generation tool for the Ruby programming language.

18 It enables the user to generate consistent, usable documentation that can be

19 exported to a number of formats very easily, and also supports extending for

20 custom Ruby constructs such as custom class level definitions. Below is a

21 summary of some of YARD's notable features.
22
23
7afd7e9 @lsegal Update README formatting
authored
24 Feature List
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
25 ------------
26
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
27 **1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible

28 with RDoc formatting. In fact, YARD does no processing on RDoc documentation

29 strings, and leaves this up to the output generation tool to decide how to

30 render the documentation.

31
32 **2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:

33 YARD uses a '@tag' style definition syntax for meta tags alongside regular code

34 documentation. These tags should be able to happily sit side by side RDoc formatted

35 documentation, but provide a much more consistent and usable way to describe

36 important information about objects, such as what parameters they take and what types
37 they are expected to be, what type a
method should return, what exceptions it can
38 raise, if it is deprecated, etc.. It also allows information to be better (and more
01461eb @lsegal Add getting started guide
authored
39 consistently) organized
during the output generation phase. You can find a list
3dbef3d @lsegal Move tag list from GettingStarted to Tags and document syntax
authored
40 of tags in the {file:Tags.md#taglist Tags.md} file.
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
41
01461eb @lsegal Add getting started guide
authored
42 YARD also supports an optional "types" declarations for certain tags.

d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
43 This allows the developer to document type signatures for ruby methods and

44 parameters in a non intrusive but helpful and consistent manner. Instead of

45 describing this data in the body of the description, a developer may formally

46 declare the parameter or return type(s) in a single line. Consider the

47 following Yardoc'd method:

48
49 # Reverses the contents of a String or IO object.
50 #
51 # @param [String, #read] contents the contents to reverse
52 # @return [String] the contents reversed lexically
53 def reverse(contents)
54 contents = contents.read if respond_to? :read
55 contents.reverse
379227a @lsegal Add support for syntax highlighting with new RubyParser AST
authored
56 end
57
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
58 With the above @param tag, we learn that the contents parameter can either be
59 a String or any object that responds to the 'read' method, which is more

60 powerful than the textual description, which says it should be an IO object.

61 This also informs the developer that they should expect to receive a String

62 object returned by the method, and although this may be obvious for a

63 'reverse' method, it becomes very useful when the method name may not be as

64 descriptive.

7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
65
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
66 **3. Custom Constructs and Extensibility of YARD**: Take for instance the example:

7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
67
01461eb @lsegal Add getting started guide
authored
68 class A
69 class << self
70 def define_name(name, value)
71 class_eval "def #{name}; #{value.inspect} end"
72 end
73 end
74
75 # Documentation string for this name
76 define_name :publisher, "O'Reilly"
77 end
78
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
79 This custom declaration provides dynamically generated code that is hard for a
80 documentation tool to properly document without help from the developer. To

81 ease the pains of manually documenting the procedure, YARD can be extended by

82 the developer to handled the `define_name` construct and add the required

83 method to the defined methods of the class with its documentation. This makes

84 documenting external API's, especially dynamic ones, a lot more consistent for
85 consumption by the users.

7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
86
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
87 **4. Raw Data Output**: YARD also outputs documented objects as raw data (the

88 dumped Namespace) which can be reloaded to do generation at a later date, or

89 even auditing on code. This means that any developer can use the raw data to

90 perform output generation for any custom format, such as YAML, for instance.

91 While YARD plans to support XHTML style documentation output as well as

92 command line (text based) and possibly XML, this may still be useful for those
93 who would like to reap the benefits of YARD's processing in other forms, such

94 as throwing all the documentation into a database. Another useful way of

95 exploiting this raw data format would be to write tools that can auto generate
96 test cases, for example, or show possible unhandled exceptions in code.

52b8234 @lsegal Add special installation instructions for some Ubuntu/Debian installa…
authored
97
98
99 Installing
100 ----------
101
102 To install YARD, use the following command:
103
104 $ gem install yard
105
106 (Add `sudo` if you're installing under a POSIX system as root)
107
108 Alternatively, if you've checked the source out directly, you can call
109 `rake install` from the root project directory.
110
111 **Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
112 install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
113 If running `which rdoc` turns up empty, install RDoc by issuing:
114
115 $ sudo apt-get install rdoc
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
116
117
7afd7e9 @lsegal Update README formatting
authored
118 Usage
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
119 -----
120
121 There are a couple of ways to use YARD. The first is via command-line, and the
122 second is the Rake task. There are also the `yard-graph` and `yri` binaries to
123 look at, if you want to poke around.
124
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
125 **1. yardoc Command-line Tool**
126
127 The most obvious way to run YARD is to run the `yardoc` binary file that comes
128 with YARD. This will, among other things, generate the HTML documentation for
129 your project code. You can type `yardoc --help` to see the options
130 that YARD provides, but the easiest way to generate docs for your code is to
131 simply type `yardoc` in your project root. This will assume your files are
132 located in the `lib/` directory. If they are located elsewhere, you can specify
133 paths and globs from the commandline via:
134
01461eb @lsegal Add getting started guide
authored
135 $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
136
137 The tool will generate a `.yardoc` file which will store the cached database
138 of your source code and documentation. If you want to re-generate your docs
139 with another template you can simply use the `--use-cache` (or -c)
140 option to speed up the generation process by skipping source parsing.
141
142 YARD will by default only document code in your public visibility. You can
143 document your protected and private code by adding `--protected` or
aee74c6 @lsegal Update docs to reflect new YARD behaviours
authored
144 `--private` to the option switches. In addition, you can add `--no-private`
145 to also ignore any object that has the `@private` meta-tag. This is similar
146 to RDoc's ":nodoc:" behaviour, though the distinction is important. RDoc
147 implies that the object with :nodoc: would not be documented, whereas
148 YARD still recommends documenting private objects for the private API (for
149 maintainer/developer consumption).
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
150
aee74c6 @lsegal Update docs to reflect new YARD behaviours
authored
151 You can also add extra informative files (README, LICENSE) by separating
152 the globs and the filenames with '-'.
01461eb @lsegal Add getting started guide
authored
153
aee74c6 @lsegal Update docs to reflect new YARD behaviours
authored
154 $ yardoc 'app/**/*.rb' - README LICENSE FAQ
155
156 If no globs preceed the '-' argument, the default glob (lib/**/*.rb) is
157 used:
01461eb @lsegal Add getting started guide
authored
158
aee74c6 @lsegal Update docs to reflect new YARD behaviours
authored
159 $ yardoc - README LICENSE FAQ
160
161 Note that the README file can be specified with its own `--readme` switch.
01461eb @lsegal Add getting started guide
authored
162
163 You can also add a `.yardopts` file to your project directory which lists
164 the switches separated by whitespace (newlines or space) to pass to yardoc
165 whenever it is run.
166
abeac7d @lsegal Document new --query parameter
authored
167 <h4>Queries</h4>
168
169 The `yardoc` tool also supports a `--query` argument to only include objects
170 that match a certain data or meta-data query. The query syntax is Ruby, though
171 a few shortcuts are available. For instance, to document only objects that have
172 an "@api" tag with the value "public", all of the following syntaxes would give
173 the same result:
174
175 --query '@api.text == "public"'
176 --query 'object.has_tag?(:api) && object.tag(:api).text == "public"'
177 --query 'has_tag?(:api) && tag(:api).text == "public"'
178
179 Note that the "@tag" syntax returns the first tag named "tag" on the object.
180 To return the array of all tags named "tag", use "@@tag".
181
182 Multiple `--query` arguments are allowed in the command line parameters. The
183 following two lines both check for the existence of a return and param tag:
184
185 --query '@return' --query '@param'
186 --query '@rturn && @param'
187
188 For more information about the query syntax, see the {YARD::Verifier} class.
189
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
190 **2. Rake Task**
191
192 The second most obvious is to generate docs via a Rake task. You can do this by
193 adding the following to your `Rakefile`:
194
01461eb @lsegal Add getting started guide
authored
195 YARD::Rake::YardocTask.new do |t|
196 t.files = ['lib/**/*.rb', OTHER_PATHS] # optional
197 t.options = ['--any', '--extra', '--opts'] # optional
198 end
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
199
200 both the `files` and `options` settings are optional. `files` will default to
201 `lib/**/*.rb` and `options` will represents any options you might want
202 to add. Again, a full list of options is available by typing `yardoc --help`
203 in a shell. You can also override the options at the Rake command-line with the
204 OPTS environment variable:
205
aee74c6 @lsegal Update docs to reflect new YARD behaviours
authored
206 $ rake yard OPTS='--any --extra --opts'
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
207
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
208 **3. `yri` RI Implementation**
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
209
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
210 The yri binary will use the cached .yardoc database to give you quick ri-style
211 access to your documentation. It's way faster than ri but currently does not
212 work with the stdlib or core Ruby libraries, only the active project. Example:
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
213
01461eb @lsegal Add getting started guide
authored
214 $ yri YARD::Handlers::Base#register
abeac7d @lsegal Document new --query parameter
authored
215 $ yri File.relative_path
216
217 Note that class methods must not be referred to with the "::" namespace
218 separator. Only modules, classes and constants should use "::".
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
219
303d15e @lsegal Bump version to 0.5.0
authored
220 You can also do lookups on any installed gems. Just make sure to build the
221 .yardoc databases for installed gems with:
222
223 $ sudo yardoc --build-gems
224
225 If you don't have sudo access, it will write these files to your `~/.yard`
226 directory. `yri` will also cache lookups there.
227
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
228 **4. `yard-graph` Graphviz Generator**
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
229
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
230 You can use `yard-graph` to generate dot graphs of your code. This, of course,
231 requires [Graphviz](http://www.graphviz.org) and the `dot` binary. By default
232 this will generate a graph of the classes and modules in the best UML2 notation
233 that Graphviz can support, but without any methods listed. With the `--full`
234 option, methods and attributes will be listed. There is also a `--dependencies`
235 option to show mixin inclusions. You can output to stdout or a file, or pipe directly
236 to `dot`. The same public, protected and private visibility rules apply to yard-graph.
237 More options can be seen by typing `yard-graph --help`, but here is an example:
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
238
01461eb @lsegal Add getting started guide
authored
239 $ yard-graph --protected --full --dependencies
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
240
241
7afd7e9 @lsegal Update README formatting
authored
242 Changelog
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
243 ---------
244
2e95dd9 @lsegal Bump to version 0.5.8
authored
245 - **June.22.10**: 0.5.8 release
246 - Merge fix from 0.6 branch for --no-private visibility checking
247
f9f6153 @lsegal Bump to version 0.5.7
authored
248 - **June.21.10**: 0.5.7 release
249 - Fixed visibility flag parsing in `yardoc`
250 - Updated Parser Architecture documentation with new SourceParser API
251 - Improved Registry documentation for new load commands
252 - Fix loading of .yardoc file as cache (and preserving aliases)
253 - Fix "lib" directory missing when running YARD on installed gems
254
3a5cd0b @lsegal Release 0.5.6
authored
255 - **June.12.10**: 0.5.6 release
256 - Bug fixes for RubyGems plugin, `has_rdoc=false` should now work
257 - New API for registering custom parsers. See {file:WhatsNew.md}
258
61e6769 @lsegal Bump version to 0.5.5
authored
259 - **May.22.10**: 0.5.5 release
260 - Various bug fixes
261
218a790 @lsegal Bump version 0.5.4
authored
262 - **March.22.10**: 0.5.4 release
263 - See {file:docs/WhatsNew.md what's new document} for changes
264
2e400cd @lsegal Add info to changelog
authored
265 - **January.11.10**: 0.5.3 release
7a6ef0a @lsegal Fix links in README
authored
266 - See {file:docs/WhatsNew.md what's new document} for changes
2e400cd @lsegal Add info to changelog
authored
267
268 - **December.16.09**: 0.5.2 release
7a6ef0a @lsegal Fix links in README
authored
269 - See {file:docs/WhatsNew.md what's new document} for changes
2e400cd @lsegal Add info to changelog
authored
270
271 - **December.15.09**: 0.5.1 release
7a6ef0a @lsegal Fix links in README
authored
272 - See {file:docs/WhatsNew.md what's new document} for changes
2e400cd @lsegal Add info to changelog
authored
273
274 - **December.13.09**: 0.5.0 release
7a6ef0a @lsegal Fix links in README
authored
275 - See {file:docs/WhatsNew.md what's new document} for changes
2e400cd @lsegal Add info to changelog
authored
276
cf6ed42 @lsegal Document new features in changelog section
authored
277 - **November.15.09**: 0.4.0 release
278 - Added new templating engine based on [tadpole](http://github.com/lsegal/tadpole)
279 - Added YARD queries (`--query` CLI argument to yardoc)
280 - Greatly expanded YARD documentation
281 - Added plugin support
282 - New `@abstract` and `@private` tags
283 - Changed default rake task to `rake yard`
284 - Read about changes in {file:WhatsNew.md}
285
286 - **August.13.09**: 0.2.3.5 release
287 - Minor bug fixes.
288
289 - **August.07.09**: 0.2.3.4 release
290 - Minor bug fixes.
291
292 - **July.26.09**: 0.2.3.3 release
293 - Minor bug fixes.
294
eb287b9 @lsegal Bump version to 0.2.3.2
authored
295 - **July.06.09**: 0.2.3.2 release
296 - Fix Textile hard-break issues
297 - Add description for @see tag to use as link title in HTML docs.
298 - Add --title CLI option to specify a title for HTML doc files.
299 - Add custom.css file that can be overridden with various custom
300 styelsheet declarations. To use this, simply add `default/fulldoc/html/custom.css`
301 inside your code directory and use the `-t` template directory yardoc CLI
302 option to point to that template directory (the dir holding 'default').
303 - Add support in `yardoc` CLI to specify extra files (formerly --files)
304 by appending "- extra files here" after regular source files. Example:
305
306 yardoc --private lib/**/*.rb - FAQ LICENSE
307
f39eaa6 @lsegal Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of
authored
308 - **Jun.13.09**: 0.2.3.1 release.
309 - Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of
1e244ee @lsegal Update changelog
authored
310 RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your
311 .gemspec file.
f39eaa6 @lsegal Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of
authored
312
ac0de0b @lsegal Fix file: links
authored
313 - **Jun.07.09**: 0.2.3 release. See the {file:WhatsNew.md} file for a
01461eb @lsegal Add getting started guide
authored
314 list of important new features.
315
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
316 - **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's
317 conception and involves a complete overhaul of the parser and API to make it
318 more robust and far easier to extend and use for the developer.
319
320 - **Feb.20.08**: 0.2.1 release.
321
322 - **Feb.24.07**: Released 0.1a experimental version for testing. The goal here is
323 to get people testing YARD on their code because there are too many possible
324 code styles to fit into a sane amount of test cases. It also demonstrates the
325 power of YARD and what to expect from the syntax (Yardoc style meta tags).
2e95dd9 @lsegal Bump to version 0.5.8
authored
326
327
328 Contributors
329 ------------
330
331 Special thanks to the following people for submitting patches:
332
333 * Aman Gupta
334 * Benjamin Bock
335 * Denis Defreyne
336 * Duane Johnson
337 * Elliottcable
338 * James Rosen
339 * Jeff Rafter
340 * Leonid Borisenko
341 * Loren Segal
342 * Michael Edgar
343 * Nathan Weizenbaum
344 * Postmodern
345 * Yehuda Katz
346
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
347
7afd7e9 @lsegal Update README formatting
authored
348 Copyright
d4dcea9 @lsegal Fix broken formatting in README.markdown
authored
349 ---------
7910f84 @lsegal Fix recognition of markdown in readme's, move default :readme option …
authored
350
f822d84 @lsegal Add Ruby/RDoc license information to YARD and update copyright years.
authored
351 YARD &copy; 2007-2010 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
352 licensed under the MIT license except for some files which come from the
353 RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
354 documents for more information.
Something went wrong with that request. Please try again.