lsegal-yard 0.2.3 → 0.2.3.5

data/.yardopts

@@ -0,0 +1,12 @@
+-
+docs/WHATSNEW.markdown
+docs/GETTING_STARTED.markdown
+docs/OVERVIEW.markdown
+docs/CODE_OBJECTS.markdown
+docs/TAGS.markdown
+docs/PARSER.markdown
+docs/HANDLERS.markdown
+docs/GENERATORS.markdown
+docs/FAQ.markdown
+docs/GLOSSARY.markdown
+LICENSE

data/README.markdown

@@ -1,5 +1,5 @@
-YARD Release 0.2.2 (June 16th 2008) 
-===================================
+YARD Release 0.2.3.4 (August 7th 2009)
+=====================================
 
 **Homepage**:  [http://yard.rubyforge.org](http://yard.rubyforge.org)   
 **IRC**:       **Join us on IRC in #yard on irc.freenode.net!**   
@@ -34,45 +34,10 @@ documentation, but provide a much more consistent and usable way to describe
 important information about objects, such as what parameters they take and what types
 they are expected to be, what type a
method should return, what exceptions it can 
 raise, if it is deprecated, etc.. It also allows information to be better (and more 
-consistently) organized
during the output generation phase. Some of the main tags 
-are listed below:

-                                                                              
-#### Table 1. Meta-tags and their descriptions
-                                                                              
-##### `@param [Types] name Description`
-Allows for the definition of a method parameter with
optional type information.
-                                                                              
-##### `@yieldparam [Types] name Description`
-Allows for the definition of a method parameter to a yield block with optional
-type information.
-   
-##### `@yield [paramnames] Description`
-Allows the developer to document the purpose of a yield block in a method.
-   
-##### `@return [Types] Description`
-Describes what the method returns with optional type information.
-
-##### `@deprecated Description`
-Informs the developer that a method is deprecated and should no 
-longer be used. The description offers the developer an alternative 
-solution or method for the problem.
-                                                 
-##### `@raise [Class] Description`
-Tells the developer that the method may raise an exception and of what type. 
-   
-##### `@see name`
-References another object, URL, or other for extra information. 
-
-##### `@since number`
-Lists the version number in which the object first appeared. 
-
-##### `@version number`
-Lists the current version of the documentation for the object. 
+consistently) organized
during the output generation phase. You can find a list
+of tags in the {file:
GETTING_STARTED.markdown#taglist GETTING_STARTED.markdown} file.
 
-##### `@author name`supports an optional "types" declarations for certain tags.

-The authors responsible for the module
-
-You might have noticed the optional "types" declarations for certain tags.

+YARD also supports an optional "types" declarations for certain tags.

 This allows the developer to document type signatures for ruby methods and

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

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

@@ -99,17 +64,17 @@ descriptive.
                                                                               
 **3. Custom Constructs and Extensibility of YARD**: Take for instance the example:

    
-     class A 
-       class << self 
-         def define_name(name, value) 
-           class_eval "def #{name}; #{value.inspect} end" 
-         end 
-       end 
-       
-       # Documentation string for this name 
-       define_name :publisher, "O'Reilly"
-     end
-                                                                              
+    class A 
+      class << self 
+        def define_name(name, value) 
+          class_eval "def #{name}; #{value.inspect} end" 
+        end 
+      end 
+ 
+      # Documentation string for this name 
+      define_name :publisher, "O'Reilly"
+    end
+                                                                        
 This custom declaration provides dynamically generated code that is hard for a
 documentation tool to properly document without help from the developer. To

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

@@ -147,7 +112,7 @@ simply type `yardoc` in your project root. This will assume your files are
 located in the `lib/` directory. If they are located elsewhere, you can specify
 paths and globs from the commandline via:
 
-      $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
+    $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
 
 The tool will generate a `.yardoc` file which will store the cached database
 of your source code and documentation. If you want to re-generate your docs
@@ -158,15 +123,26 @@ YARD will by default only document code in your public visibility. You can
 document your protected and private code by adding `--protected` or
 `--private` to the option switches.
 
+You can also add extra informative files with the `--files` switch,
+for example:
+
+    $ yardoc --files FAQ,LICENSE
+
+Note that the README file is specified with its own `--readme` switch.
+
+You can also add a `.yardopts` file to your project directory which lists
+the switches separated by whitespace (newlines or space) to pass to yardoc 
+whenever it is run.
+
 **2. Rake Task**
 
 The second most obvious is to generate docs via a Rake task. You can do this by 
 adding the following to your `Rakefile`:
 
-      YARD::Rake::YardocTask.new do |t|
-        t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
-        t.options = ['--any', '--extra', '--opts'] # optional
-      end
+    YARD::Rake::YardocTask.new do |t|
+      t.files   = ['lib/**/*.rb', OTHER_PATHS]   # optional
+      t.options = ['--any', '--extra', '--opts'] # optional
+    end
 
 both the `files` and `options` settings are optional. `files` will default to
 `lib/**/*.rb` and `options` will represents any options you might want
@@ -174,7 +150,7 @@ to add. Again, a full list of options is available by typing `yardoc --help`
 in a shell. You can also override the options at the Rake command-line with the
 OPTS environment variable:
 
-      $ rake yardoc OPTS='--any --extra --opts'
+    $ rake yardoc OPTS='--any --extra --opts'
                                                                               
 **3. `yri` RI Implementation**
 
@@ -182,8 +158,8 @@ The yri binary will use the cached .yardoc database to give you quick ri-style
 access to your documentation. It's way faster than ri but currently does not
 work with the stdlib or core Ruby libraries, only the active project. Example:
 
-      $ yri YARD::Handlers::Base#register
-      $ yri File::relative_path
+    $ yri YARD::Handlers::Base#register
+    $ yri File::relative_path
 
 **4. `yard-graph` Graphviz Generator**
 
@@ -196,12 +172,33 @@ option to show mixin inclusions. You can output to stdout or a file, or pipe dir
 to `dot`. The same public, protected and private visibility rules apply to yard-graph.
 More options can be seen by typing `yard-graph --help`, but here is an example:
 
-      $ yard-graph --protected --full --dependencies
+    $ yard-graph --protected --full --dependencies
 
 
 CHANGELOG
 ---------
 
+- **July.06.09**: 0.2.3.2 release
+    - Fix Textile hard-break issues
+    - Add description for @see tag to use as link title in HTML docs.
+    - Add --title CLI option to specify a title for HTML doc files.
+    - Add custom.css file that can be overridden with various custom
+      styelsheet declarations. To use this, simply add `default/fulldoc/html/custom.css`
+      inside your code directory and use the `-t` template directory yardoc CLI
+      option to point to that template directory (the dir holding 'default').
+    - Add support in `yardoc` CLI to specify extra files (formerly --files)
+      by appending "- extra files here" after regular source files. Example:
+
+            yardoc --private lib/**/*.rb - FAQ LICENSE
+
+- **Jun.13.09**: 0.2.3.1 release.
+    - Add a RubyGems 1.3.2+ plugin to generate YARD documentation instead of
+      RDoc. To take advantage of this plugin, set `has_rdoc = 'yard'` in your
+      .gemspec file.
+
+- **Jun.07.09**: 0.2.3 release. See the {file:WHATSNEW.markdown} file for a 
+  list of important new features.
+
 - **Jun.16.08**: 0.2.2 release. This is the largest changset since yard's 
   conception and involves a complete overhaul of the parser and API to make it
   more robust and far easier to extend and use for the developer.

data/Rakefile

@@ -26,9 +26,13 @@ desc "Run all specs"
 Spec::Rake::SpecTask.new("specs") do |t|
   $DEBUG = true if ENV['DEBUG']
   t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_opts += ["--require", File.join(File.dirname(__FILE__), 'spec', 'spec_helper')]
   t.spec_files = Dir["spec/**/*_spec.rb"].sort
+  t.rcov = true if ENV['RCOV']
+  t.rcov_opts = ['-x', '_spec\.rb$,spec_helper\.rb$']
 end
+task :spec => :specs
 
 YARD::Rake::YardocTask.new do |t|
-  t.options = ["--files", "FAQ.markdown,LICENSE"]
-end
+  t.after = lambda { `cp -R docs/images/ doc/images/` }
+end

data/bin/yri

@@ -3,11 +3,18 @@ require File.dirname(__FILE__) + '/../lib/yard'
 
 YARD::Registry.load
 
+if ARGV[0] == '-T' || ARGV[0] == '--no-pager'
+  output = YARD::Serializers::StdoutSerializer.new
+  ARGV.shift
+else
+  output = YARD::Serializers::ProcessSerializer.new('less')
+end
+
 object = YARD::Registry.at(ARGV[0])
 options = {
   :format => :text, 
   :template => :default, 
-  :serializer => YARD::Serializers::ProcessSerializer.new('less')
+  :serializer => output
 }
 
 YARD::Generators::QuickDocGenerator.new(options).generate(object)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: lsegal-yard
 version: !ruby/object:Gem::Version 
-  version: 0.2.3
+  version: 0.2.3.5
 platform: ruby
 authors: 
 - Loren Segal
@@ -9,12 +9,12 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-05-16 00:00:00 -07:00
+date: 2009-08-13 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: 
-email: lsegal, soen.ca
+description: YARD is a documentation generation tool for the Ruby programming language. It enables the user to generate consistent, usable documentation that can be exported to a number of formats very easily, and also supports extending for custom Ruby constructs such as custom class level definitions.
+email: lsegal@soen.ca
 executables: 
 - yardoc
 - yri
@@ -25,10 +25,10 @@ extra_rdoc_files: []
 
 files: 
 - LICENSE
-- FAQ.markdown
 - README.markdown
 - Rakefile
-has_rdoc: false
+- .yardopts
+has_rdoc: yard
 homepage: http://yard.soen.ca
 post_install_message: 
 rdoc_options: []

data/FAQ.markdown

@@ -1,28 +0,0 @@
-FAQ
-===
-
-1. **So, show me some cool stuff.  What can YARD do?**
-  - [Visualize with GraphViz][graphviz] Visualize your classes and methods with GraphViz
-  - [Inline RSpecs][inline-rspecs] In your rspec files, call the following to refer back to and call the inline rspecs: `described_in_docs "String", "camelcase"`
-  - [Inline doc testing][inline-doctest] Use the 'docspec' command line tool to run the above tests.  This is similar to [Ruby DocTest][rubdoctest]'s inline irb testing.
-  
-2. **Why did you pick the @-symbol tags for documentation?**
-
-  Java, C++, Python and many other languages have standard documentation tools that use the @tag "standard".  This has been extended to the Ruby language, and YARD takes advantage of this common style.
-
-3. **Can I tweak it to use some other documentation standard?**
-
-  Yes. YARD is flexible enough to have other documentation syntaxes put into use. [TODO: Add information about customization here.]
-
-4. **Why don't you use ParseTree, or sydparse?  Why did you write your own parser?**
-
-  All ruby parsers that we are aware of have two limitations that are unacceptable to a documentation parser:
-  1. They do not put comments into the parse tree.
-  2. They all fail ungracefully on parse errors.
-  
-  As a result, YARD uses its own ruby parser that pays particular attention to the comment sections so that all of the information that is needed can be gleened from code and comments alike.
-
-[graphviz]:http://gnuu.org/2008/02/29/generating-class-diagrams-with-yard-and-graphviz/
-[inline-rspecs]:http://github.com/lsegal/yard/tree/5b07d706eee6bc0d7f13d9ec1e6e0ab914d3679c/lib/yard/core_ext/string.rb
-[inline-doctest]:http://github.com/lsegal/yard/tree/master/lib/yard/handlers/base.rb#L350
-[rubydoctest]:http://github.com/tablatom/rubydoctest