yard 0.6.8 → 0.7.0

data/README.md

@@ -8,8 +8,8 @@ YARD: Yay! A Ruby Documentation Tool
 **Contributors**: See Contributors section below    
 **Copyright**:    2007-2011    
 **License**:      MIT License    
-**Latest Version**: 0.6.7 (codename "No codename")    
-**Release Date**: April 6th 2011    
+**Latest Version**: 0.7.0 (codename "Heroes")    
+**Release Date**: May 17th 2011    
 
 Synopsis
 --------
@@ -139,7 +139,7 @@ YARD server, and so on. To view a list of available YARD commands, type:
 Plugins can also add commands to the `yard` executable to provide extra
 functionality.
 
-#### Generating Documentation
+### Generating Documentation
 
 <span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
 
@@ -183,7 +183,7 @@ the switches separated by whitespace (newlines or space) to pass to yardoc
 whenever it is run. A full overview of the `.yardopts` file can be found in
 {YARD::CLI::Yardoc}.
 
-#### Queries
+### Queries
 
 The `yardoc` tool also supports a `--query` argument to only include objects
 that match a certain data or meta-data query. The query syntax is Ruby, though
@@ -254,14 +254,14 @@ RubyGems. To serve documentation for a project you are working on, simply run:
 And the project inside the current directory will be parsed (if the source has
 not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
 
-#### Live Reloading
+### Live Reloading
 
 If you want to serve documentation on a project while you document it so that
 you can preview the results, simply pass `--reload` (`-r`) to the above command
 and YARD will reload any changed files on each request. This will allow you to
 change any documentation in the source and refresh to see the new contents.
 
-#### Serving Gems
+### Serving Gems
 
 To serve documentation for all installed gems, call:
 
@@ -289,6 +289,16 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
 Changelog
 ---------
 
+- **May.17.11**: 0.7.0 release
+    - See the {docs/WhatsNew.md} document for details on added features
+    - Make sure that Docstring#line_range is filled when possible (#243)
+    - Set #verifier in YardocTask (#282)
+    - Parse BOM in UTF-8 files (#288)
+    - Fix instance attributes not showing up in method list (#302)
+    - Fix rendering of %w() literals in constants (#306)
+    - Ignore keyboard shortcuts when an input is active (#312)
+    - And more...
+
 - **April.14.11**: 0.6.8 release
     - Fix regression in RDoc 1.x markup loading
     - Fix regression in loading of markup libraries for `yard server`

data/docs/CodeObjects.md

@@ -1,13 +1,13 @@
-CodeObjects Architecture
-========================
+# @title CodeObjects Architecture
+
+# CodeObjects Architecture
 
 Code objects are Ruby objects that describe the code being documented. For instance,
 all classes, modules, methods, etc. are all extracted from the Ruby source as code
 objects. All of these code objects extend from the {YARD::CodeObjects::Base} class, which
 provides basic attributes like source location, source code, name and path.
 
-CodeObjects Organization
-------------------------
+## CodeObjects Organization
 
 Code objects are divided into two basic types. {YARD::CodeObjects::NamespaceObject NamespaceObjects}
 and non-namespace objects. A namespace object refers to any object in Ruby that can have
@@ -23,8 +23,7 @@ The following is an overview of the classes within the `CodeObjects` namespace:
 
 ![CodeObjects Class Diagram](images/code-objects-class-diagram.png)
 
-Unique Path Representation
---------------------------
+## Unique Path Representation
 
 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
@@ -41,8 +40,7 @@ would have the following respective paths:
 * Constant `VERSION` inside class `YARD`: `YARD::VERSION`
 * Class variable `@@abc` inside class `A`: `A::@@abc`
 
-Registry
---------
+## Registry
 
 CodeObjects classes are coupled with the {YARD::Registry} class which keeps track of
 all instantiated code objects. This is an explicit design choice to allow objects
@@ -51,8 +49,7 @@ above, this coupling is a result of the fact that each object is uniquely identi
 its path, which is used to implement lookups. You can read more about the registry 
 in the {YARD::Registry} class.
 
-Identity Map
-------------
+## Identity Map
 
 Code objects are instantiated using an identity-map like implementation that guarantees
 only one unique Ruby object exists for an object described by a specific path. This
@@ -62,8 +59,7 @@ 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 
 
-Proxy Objects
--------------
+## Proxy Objects
 
 In addition to providing access to existing objects, a {YARD::CodeObjects::Proxy}
 class exists which can represent an object at a path that may or may not have been
@@ -80,8 +76,7 @@ for example:
     P(:InvalidObject).type == :proxy  #=> true
     P(:InvalidObject).is_a?(Proxy)    #=> true
 
-Adding Data to Code Objects
----------------------------
+## Adding Data to Code Objects
 
 Code objects act as hash-like structures that allow any arbitrary value to be set.
 This allows easy extending of existing objects without creating custom subclasses.
@@ -96,8 +91,7 @@ well as like any other method:
 
     object.modified_at #=> 2009-06-03 20:08:46 -0400
 
-Creating a Custom CodeObject
-----------------------------
+## Creating a Custom CodeObject
 
 It should first be mentioned that creating a custom code object should not be
 necessary in most cases, except when functionality that cannot be represented

data/docs/GettingStarted.md

@@ -1,5 +1,6 @@
-Getting Started with YARD
-=========================
+# @title Getting Started Guide
+
+# Getting Started with YARD
 
 There are a few ways which YARD can be of use to you or your project. This 
 document will cover the most common ways to use YARD:
@@ -12,8 +13,8 @@ document will cover the most common ways to use YARD:
 * [Plugin Support](#plugins)
 
 <a name="docing"></a>
-Documenting Code with YARD
-==========================
+
+## Documenting Code with YARD
 
 By default, YARD is compatible with the same RDoc syntax most Ruby developers
 are already familiar with. However, one of the biggest advantages of YARD is
@@ -60,8 +61,7 @@ Using tags we can add semantic metadata to our code without worrying about
 presentation. YARD will handle presentation for us when we decide to generate
 documentation later.
 
-Which Markup Format?
---------------------
+## Which Markup Format?
 
 YARD does not impose a specific markup. The above example uses standard RDoc
 markup formatting, but YARD also supports textile and markdown via the 
@@ -71,8 +71,7 @@ using markdown. YARD, however, does add a few important syntaxes that are
 processed no matter which markup formatting you use, such as tag support 
 and inter-document linking. These syntaxes are discussed below.
 
-Adding Tags to Documentation
-----------------------------
+## Adding Tags to Documentation
 
 The tag syntax that YARD uses is the same @tag-style syntax you may have seen 
 if you've ever coded in Java, Python, PHP, Objective-C or a myriad of other 
@@ -149,8 +148,7 @@ and return tags:
 The above copies all of the param and return tags from `#get`. Note that you
 cannot copy individual tags of a specific type with this syntax.
 
-Declaring Types
----------------
+## Declaring Types
 
 Some tags also have an optional "types" field which let us declare a list of
 types associated with the tag. For instance, a return tag can be declared
@@ -186,15 +184,130 @@ and recommended conventions for writing type specifications, see
 {http://yardoc.org/types.html}. Note that these conventions may change every now 
 and then, although we are working on a more "formal" type specification proposal.
 
-Inter-document Linking
-----------------------
+## Documenting DSL Methods
+
+Application code in Ruby often makes use of DSL style metaprogrammed methods.
+The most common is the `attr_accessor` method, which of course has built-in
+support in YARD. However, frameworks and libraries often expose custom
+methods that perform similar metaprogramming tasks, and it is often useful
+to document their functionality in your application. Consider the `property`
+method in a project like {http://datamapper.org DataMapper}, which creates
+a typed attribute for a database model. The code might look like:
+
+    class Post
+      include DataMapper::Resource
+      
+      property :title, String
+    end
+    
+As of version 0.7.0, YARD will automatically pick up on these basic methods if
+you document them with a docstring. Therefore, simply adding some comments to
+the code will cause it to generate documentation:
+
+    class Post
+      include DataMapper::Resource
+      
+      # @return [String] the title property of the post
+      property :title, String
+    end
+
+Note that YARD uses the first argument in the method call to determine the
+method name. In some cases, this would not be the method name, and you would
+need to declare it manually. You can do so with the `@method` tag:
+
+    # @method foo
+    create_a_foo_method
+    
+The @method tag can also accept a full method signature with parameters:
+
+    # @method foo(name, opts = {})
+    create_a_foo_method
+
+You can also set visibility and scope, or modify the method signature with
+extra tags. The following adds documentation for a private class method:
+
+    # @method foo(opts = {})
+    # The foo method!
+    # @scope class
+    # @visibility private
+    create_a_private_foo_class_method
+    
+Finally, you can tag a method as an attribute by replacing the @method
+tag with @attribute. The @attribute tag allows for the flags [r], [w], or
+[rw] to declare a readonly, writeonly, or readwrite attribute, respectively.
+
+    # @attribute [w]
+    # The writeonly foo attribute!
+    a_writeonly_attribute :foo
+    
+(Note that if the name can be automatically detected, you do not need to
+specify it in the @method or @attribute tag)
+    
+However, you will notice a few drawbacks with this basic support:
+
+1. There is a fair bit of duplication in such documentation. Specifically, we
+   repeat the term String and title twice in the property example.
+2. We must write a code comment for this property to show up in the documentation.
+   If we do not write a comment, it is ignored.
+
+### Macros
+   
+Fortunately YARD 0.7.0 also adds macros, a powerful way to add support for
+these DSL methods on the fly without writing extra plugins. Macros allow
+you to interpolate arguments from the method call inside the docstring,
+reducing duplication. If we re-wrote the `property` example from above
+using a macro, it might look like:
+
+    class Post
+      include DataMapper::Resource
+  
+      # @macro dm.property
+      # @return [$2] the $1 $0 of the post
+      property :title, String
+    end
+
+(Note that $0 represents the method call, in this case `property`. The rest
+are arguments in the method call.)
+
+The above example is equivalent to the first version shown in the previous
+section. There is also some extra benefit to using this macro, in that we
+can re-apply it to any other property in our class by simply calling on
+the macro. The following:
+
+    # @macro dm.property
+    property :view_count, Integer
+
+Would be equivalent to:
+
+    # @return [Integer] the view_count property of the post
+    property :view_count, Integer
+
+Finally, macros can be "attached" to method calls, allowing them to be implicitly
+activated every time the method call is seen in the source code of the class,
+or an inheriting class. By simply adding the `[attach]` flag, the macro
+becomes implicit on future calls. All of the properties below get documented
+by using this snippet:
+
+    class Post
+      include DataMapper::Resource
+
+      # @macro [attach] dm.property
+      # @return [$2] the $1 $0 of the post
+      property :title, String
+      property :view_count, Integer
+      property :email, String
+    end
+
+You can read more about macros in the {file:docs/Tags.md Tags Overview} document.
+
+## Customized YARD Markup
 
 YARD supports a special syntax to link to other code objects, URLs, files,
 or embed docstrings between documents. This syntax has the general form
 of `{Name OptionalTitle}` (where `OptionalTitle` can have spaces, but `Name`
 cannot).
 
-### Linking Objects
+### Linking Objects `{...}`
 
 To link another "object" (class, method, module, etc.), use the format:
 
@@ -212,14 +325,14 @@ the link syntax in this tag:
     # @see #methodname   <- Correct.
     # @see {#methodname} <- Incorrect.
     
-### Linking URLs
+### Linking URLs `{http://...}`
 
 URLs are also linked using this `{...}` syntax:
 
     {http://example.com Optional Title}
     {mailto:email@example.com}
 
-### Linking Files
+### Linking Files `{file:...}`
 
 Files can also be linked using this same syntax but by adding the `file:`
 prefix to the object name. Files refer to extra readme files you added
@@ -230,7 +343,7 @@ via the command-line. Consider the following examples:
     
 As shown, you can also add an optional `#anchor` if the page is an HTML link.
 
-### Embedding Docstrings
+### Embedding Docstrings `{include:...}`
 
 We saw the `(see ...)` syntax above, which allowed us to link an entire docstring
 with another. Sometimes, however, we just want to copy docstring text without
@@ -248,14 +361,43 @@ The docstring for Bar becomes:
 
     "This is another class. This class is cool too!"
 
-Note that this prefix currently only works for objects.
+### Embedding Files `{include:file:...}`
+
+You can embed the contents of files using `{include:file:path/to/file}`, 
+similar to the `{include:OBJECT}` tag above. If the file uses a specific markup
+type, it will be applied and embedded as marked up text. The following
+shows how the tag can be used inside of comments:
+
+    # Here is an example of a highlighted Ruby file:
+    #
+    # {include:file:examples/test.rb}
+    
+### Rendering Objects `{render:...}`
+
+Entire objects can also be rendered in place in documentation. This can be
+used for guide-style documentation which does not document the entire source
+tree, but instead selectively renders important classes or methods. Consider
+the following documentation inside of a README file:
+
+    = igLatinPay!
+    
+    This library adds pig latin methods to the string class, allowing you
+    to transform sentences into pig latin.
+    
+    {render:String#pig_latin}
+    
+    You can also un-pig-latin-ify a word or sentence:
+    
+    {render:String#de_pig_latin}
+    
+The above would render the methods in place inside the README document,
+allowing you to summarize a small library in a single file.
 
 <a name="using"></a>
-Using YARD to Generate Documentation
-====================================
 
-`yard` Executable
------------------
+## Using YARD to Generate Documentation
+
+### `yard` Executable
 
 YARD ships with a single executable aptly named `yard`. In addition to
 generating standard documentation for your project, you would use this tool 
@@ -287,8 +429,7 @@ full list):
 Note that `yardoc` is an alias for `yard doc`, and `yri` is an alias for
 `yard ri`. These commands are maintained for backwards compatibility.
 
-`.yardopts` Options File
-------------------------
+### `.yardopts` Options File
 
 Unless your documentation is very small, you'll end up needing to run `yardoc`
 with many options.  The `yardoc` tool will use the options found in this file.
@@ -313,9 +454,68 @@ Any extra switches passed to the command-line now will be appended to your
 Note that options for `yardoc` are discussed in the {file:README.md README}, 
 and a full overview of the `.yardopts` file can be found in {YARD::CLI::Yardoc}.
 
-<a name="docing"></a>
-Configuring YARD
-================
+### Documenting Extra Files
+
+"Extra files" are extra guide style documents that help to give a brief overview
+of how to use your library/framework, as well as any extra information that
+might be vital for your users. The most common "extra file" is the README,
+which is automatically detected by YARD if found in the root of your project
+(any file starting with `README*`). You can specify extra files on the command
+line (or in the `.yardopts` file) by listing them after the '-' separator:
+
+    yardoc lib/**/*.rb ext/**/*.c - LICENSE.txt
+  
+Note that the README will automatically be picked up, so you do not need to
+specify it. If you don't want to modify the default file globs, you can ignore
+the first set of arguments:
+
+    yardoc - LICENSE.txt
+    
+Below you can read about how to customize the look of these extra files, both
+with markup and pretty titles.
+
+#### Adding Meta-Data to Extra Files
+
+You can add YARD-style `@tag` metadata to the top of any extra file if prefixed
+by a `#` hash comment. YARD allows for arbitrary meta-data, but pays special
+attention to the tags `@markup`, `@encoding`, and `@title`. Note that there 
+cannot be any whitespace before the tags. Here is an example of some tag data 
+in a README:
+
+    # @markup markdown
+    # @title The Best Library in the World!
+    # @author The Author Name
+    
+    This is the best library you will ever meet. Lipsum ...
+
+The `@markup` tag allows you to specify a markup format to use for the file,
+including "markdown", "textile", "rdoc", "ruby", "text", "html", or "none" 
+(no markup). This can be used when the markup cannot be auto-detected using
+the extension of the filename, if the file has no extension, or if you want
+to override the auto-detection.
+
+By using `@encoding` you can specify a non-standard encoding. Note that 
+`yardoc --charset` sets the global encoding (for all comments / files),
+so if you are using unicode across all your files, you can specify it there.
+Using the `@encoding` tag might be used to override the default global
+charset, say, if you had a localized `README.jp` file with SJIS data.
+Also note that this only affects Ruby 1.9.x, as Ruby 1.8 is not properly
+encoding aware.
+
+The `@title` tag allows you to specify a full title name for the document.
+By default, YARD uses the filename as the title of the document and lists
+it in the file list in the index and file menu. In some cases, the file name
+might not be descriptive enough, so YARD allows you to specify a full title:
+
+    contents of TITLE.txt:
+    # @title The Title of The Document
+
+Currently all other meta-data is hidden from view, though accessible
+programmatically using the {YARD::CodeObjects::ExtraFileObject} class.
+
+<a name="config"></a>
+
+## Configuring YARD
 
 YARD (0.6.2+) supports a global configuration file stored in `~/.yard/config`.
 This file is stored as a YAML file and can contain arbitrary keys and values
@@ -336,8 +536,8 @@ using the `yard config` command. To list your configuration, use `yard config --
 To view a key, use `yard config ITEM`, and to set it, use `yard config ITEM VALUE`.
 
 <a name="extending"></a>
-Extending YARD
-==============
+
+## Extending YARD
 
 There are many ways to extend YARD to support non-standard Ruby syntax (DSLs), 
 add new meta-data tags or programmatically access the intermediate metadata
@@ -353,16 +553,16 @@ For information on accessing the data YARD stores about your documentation,
 look at the {file:docs/CodeObjects.md} architecture document.
 
 <a name="templating"></a>
-Templating YARD
-===============
+
+## Templating YARD
 
 In many cases you may want to change the style of YARD's templates or add extra
 information after extending it. The {file:docs/Templates.md} architecture
 document covers the basics of how YARD's templating system works.
 
 <a name="plugins"></a>
-Plugin Support
-==============
+
+## Plugin Support
 
 As of 0.4, YARD will automatically load any gem named with the prefix of
 `yard-` or `yard_`. You can use this to load a custom plugin that