Ruby/Ruby Documentation

[edit] How to use ruby documentation

RDOC is defined as an application system which facilitates a programmer to get the source files of ruby in the documented form.It uses the names of extensions of the files to identify whether it is a ruby program file or not. Extensions having .rb and .rbw are taken to be Ruby source files and Files having extension are considered to be C source files and hence parsed accordingly. Its basic functionality includes a set of processes like the parsing of the source code and along with this, it also extracts the various class definitions along with the module and methods definitions.

Installation of RDOC:

RDOC can be installed by putting the command as

% ruby install.rb.

After the successful installation we can create the Ruby documentation by writing the line of code as

% rdoc [options]  [names...]

We can write

 % rdoc

to generate the documentation for any Ruby source file in its current directory.

We can start and execute RDoc from the command line by typing:

  % rdoc <options> [name...]

Once this command is entered and processed all the information gathered in various files is collected with the help of parsing. This exercise saves a lot of time which gets consumed in resolving all th files later. If the complete path is mentioned it directly processes that particular file and in the situation when there is no name mentioned all the ruby files which are present in the current directory will be considered for the processing.

[edit] Documented Ruby Class

The installation of the RDoc is quite an easy task to do as it comes in the pacake form with Ruby.

We will now try to write our first basic ruby class in the documented form.

And then we will save the following as The_basic_documented_ruby_class.rb file.

# An example class class TheBasicDocumentedClass   

$ rdoc The_basic_documented_ruby_class.rb 

      The_basic_documented_ruby_class.rb: c.
Generating HTML...

Files:   1
Classes: 1
Modules: 0
Methods: 1
Elapsed: 0.06s

And here it goes, we have got our ruby documentation done.

We will find that we have successfully created a doc directory which has an index.html file.

There are various Options which can be implemented on RDOC. Few of them are mentioned below with their brief functionality:

--all By default, all the public methods are considered for the purpose of execution but if all is given it will take into account all the private methods and the protected methods.

--main name This option is used to put the class or the file to be visible on the index page.

--exclude pattern All the files and the directories which match exactly with the given pattern in this option is not considered for the purpose of execution and processing.

--quiet As the option is self explanatory, if quiet is given all the messages which mention the progress will not be displayed.

--one-file Giving this option will help to get all the output in just one file.

--opname name This option will set the given output name.

--charset charset Set the character set for the generated HTML.

--fmt fmt This option will give the output in a given format.

--inline-source If this option is not given then the source code of methods is displayed in a popup. By giving this option then the source code will be displayed inline.

--diagram This option will be used to include the diagrams.

[edit] Ruby Basic Documentation Guidelines

Since the documentation that we create is also a part of our ruby source code it also should be given due importance as we give to our code at the time of programming. There are few tips that will be beneficial if taken into consideration while preparing the ruby documentation.

1. The documentation length should be restricted to maximum 80 characters. It also includes the white spaces and the comments.
2. We should try to use :: at the time of mentioning the class methods, # is used for mentioning the instance methods and . is used to show the example code.
3. The Documentation should always be written by avoiding the abbreviations or the short names as they may confuse the readers.
4. Different lines should be written with the help of comments and space should be given in between.
5. Try to give good amount of examples.
6. While defining the methods give their basic functionality, it is not required to mention it in detail.
7. Prefer giving information on each individual page with proper links in between.

RDOC in a nutshell can be said to help the developers to have any ruby source and get the structured HTML documentation from that for the purpose. It also helps to do the proper analysis of the visibility of the various methods. It also uses the mark-ups in the comments which again increases the readability of the documentation without the users being known that the document is having mark up.