EzDevInfo.com

YARD is not the same as RDoc?

Correct me if I'm wrong, is YARD not the same as RDoc?

It's not based on RDoc but a total rewrite?

So if I'm using YARD, I don't have to bother with RDoc right?

Mark a parameter as optional (or has a default) with YARD

I'm using YARD to document my code. I have a method that has an optional parameter with a default value. How do I notate that the parameter is optional and has a default value?

Example:

# Squares a number
# 
# @param the number to square
def square_a_number(number = 2)
  number * number
end

Run Yard Server on Heroku

Is there a way to mount Yard (http://yardoc.org/guides/index.html) server on heroku ? I did not find anything in the doc that explains how to do it.

Thanks a lot

How to rebuild rdoc for all the installed gems?

I have several gems installed in multiple locations.

What is the hard/easy way to generate/re-generate:

• rdoc for all these installed gems, all at once?
• yardoc for all these installed gems, all at once?

Is it normal that YARD doesn't replace `code` with code?

I'm just starting to use YARD for documenting my Rails app. I didn't specify any specific Markup handler, but I would have expected that `code` would be converted to code, which doesn't seem to happen. Is this normal behavior? Do I have to add some additional option to make this work? Thank you.

Does Ruby Yard have a feature comparable to RDoc :include: tag?

RDoc has the :include: tag (see the bottom of this page) that will take in an arbitrary text file and format as if it was indented wherever the include begins. This is a great way to pull in source code for documentation examples.

Does Yard have a similar tag or feature?

How to document AngularJS + Ruby on Rails app?

I'm using yard to generate my documentation for Rails apps from an rdoc file. There are AngularJS documentation generators, but how could they be connected to generate one coherent document for an AngularJS + Rails app?

All Ruby documentation offline with yard

If I want see documentation on my gems I can do:

yard server --gems

How can I see the documentation of Ruby's standard library?

Set Enviroment variables on Engine Yard

My app is on Engine Yard services and I need to set the environment variables to work with my secret id and password.

Somebody know how I can set each variables? What is the best way to do this?

How can I list the undocumented modules/classes/constants/methods with yardoc?

I have a small library of code that I am documenting with YARD. When I run the yardoc command, it tells me:

Files:          40
Modules:        14 (    0 undocumented)
Classes:        39 (    0 undocumented)
Constants:      21 (    4 undocumented)
Methods:       239 (   31 undocumented)
 88.82% documented

Instead of wading through all of my code to find the undocumented constants and methods, I want it to simply list the undocumented items. Anybody know how to do this?

yard and links to classes/modules in the doc

I'm currently switching from rdoc to yard for my ruby software documentaion.

In my doc I often reference some classes/modules from the comments, for instance :

## == Provides various utility features
##
## == Features
##
## Logging : logging is provided by the Mysoft::Mypackage::Utility::Logger class
##

Rdoc correctly creates a link to the Mysoft::Mypackage::Utility::Logger class documentation page, while yard ignores the tag and considers the class name as simple string.

I know that yard has the @see tag, however this will create a separate "See Also" section in the documentation, while I need to reference the class/modules with inside my description text.

I'm surely missing something, but if you have any examples on how this should be done with yard, I'd realy appreciate.

Thanks per advace,

dl

Document model attributes with YARD

I'm using YARD to generate docs for my rails app with makrdown as the script parser. Most of the documentation features just work great right out of the box. However, I'd also like to document the model attributes to one, record the list of available attributes on a model and two, to describe their semantic meaning.

I wasn't able to find any special support for this in YARD and I'm basically left with simply listing out the attributes in the class comments. Is there a way to document the dynamically generated model attributes so that they appear in the documentation like standard attributes/methods?

P.S. I've used the annodate-models gem to generate a basic schema dump at the top of the class listing but that's not really what I want.

YARD: documenting class methods added by an included module

I am writing documentation for my ruby gem using YARD. In my gem, I have some code which follows this common ruby pattern where a module is included in a class, and that module not only adds instance methods but it also adds class methods:

module Moo
  def self.included(klass)
    klass.extend ClassMethods
  end

  module ClassMethods
    def hello
      puts "hello"
    end
  end
end

class Foo
  include Moo
end

Foo.hello  # => class method runs, printing "hello"

By default, YARD will generate documentation for the Foo class that looks like this:

I think this documentation is inadequate because it does not tell the user that the Foo.hello method is available. To learn about hello, the user has to click on Moo and then click on ClassMethods.

It would be great to have a list of all the class and instance methods of Foo on one page. How can I make that happen? Do I need to change the code, or is there a tag I can add to give YARD a hint about ClassMethods?

How do I document Rake tasks with YARD?

I would like to include information on the Rake tasks in our Rails app. We use YARD for documentation, and at the moment pages like lib/tasks/development.rake show up by default as unformatted text.

I can make them render as Ruby source code using the # @markup ruby from the YARD documentation.

However, this just renders any comments inline, even if they include YARD directives like # @!method foo. This means the YARD documentation on tagging DSLs doesn’t seem to be applicable.

Am I missing something?

How can I get YARD to recognise code vs documentation in .rake files?

N.B. I would be happy with a solution that ignores the actual code and just generates documentation copy, but the source for the documentation copy must be the .rake file itself – I do not want documentation to live in a separate .markdown file (or whatever) as there’s too much chance of it getting out of sync.

How should I provide YARD/RDoc documentation for Ruby keyword arguments?

For a basic Ruby method, I would provide YARD style doc for parameters in the following format.

# @param query [String] The search string to query.
# @param options [Hash] Optional search preferences.
def search(query, options = {})
  # ...
end

With Ruby 2.0, keywords arguments can now be used. However, I'm not sure how to approach that in terms of the YARD documentation.

def search(query, exact_match: false, results_per_page: 10)
  # ...
end

How would I document for exact_match and results_per_page in the second scenario? Should I just continue to use the @param keyword, or is there something better?