Documenting Your Web Site

Problem

You want to document the controllers, models, and helpers of your web application so that the developers responsible for maintaining the application can understand how it works.

Solution

As with any other Ruby program, you document a Rails application by adding specially-formatted commands to your code. Heres how to add documentation to the FooController class and one of its methods:

	# The FooController controller contains miscellaneous functionality
	# rejected from other controllers.
	class FooController < ApplicationController
	 # The set_random action sets the @random_number instance variable
	 # to a random number.
	 def set_random
	 @random_number = rand*rand
	 end
	end

The documentation for classes and methods goes before their declaration, not after.

When youve finished adding documentation comments to your application, go to your Rails applications root directory and issue the rake appdoc command:

	$ rake appdoc

This Rake task runs RDoc for your Rails application and generates a directory called doc/app. This directory contains a web site with the aggregate of all your documentation comments, cross-referenced against the source code. Open the doc/app/index.rhtml file in any web browser, and you can browse the generated documentation.

Discussion

Your RDoc comments can contain markup and special directives: you can describe your arguments in definition lists, and hide a class or method from documentation with the :nodoc: directive. This is covered in Recipe 17.11.

The only difference between Rails applications and other Ruby programs is that Rails comes with a Rakefile that defines an appdoc task. You don have to find or write one yourself.

You probably already put inline comments inside your methods, describing the action as it happens. Since the RDoc documentation contains a formatted version of the original source code, these comments will be visible to people going through the RDoc. These comments are formatted as Ruby source code, though, not as RDoc markup.

See Also

  • Recipe 17.11, "Documenting Your Application"
  • Chapter 19, especially Recipe 19.2, "Automatically Generating Documentation"
  • The RDoc for RDoc (http://rdoc.sourceforge.net/doc/index.html)


Strings

Numbers

Date and Time

Arrays

Hashes

Files and Directories

Code Blocks and Iteration

Objects and Classes8

Modules and Namespaces

Reflection and Metaprogramming

XML and HTML

Graphics and Other File Formats

Databases and Persistence

Internet Services

Web Development Ruby on Rails

Web Services and Distributed Programming

Testing, Debugging, Optimizing, and Documenting

Packaging and Distributing Software

Automating Tasks with Rake

Multitasking and Multithreading

User Interface

Extending Ruby with Other Languages

System Administration



Ruby Cookbook
Ruby Cookbook (Cookbooks (OReilly))
ISBN: 0596523696
EAN: 2147483647
Year: N/A
Pages: 399

Flylib.com © 2008-2020.
If you may any questions please contact us: flylib@qtcs.net