Introduction

The Ruby Documenting Tool application enables you to view, edit and write comments in ruby source files in more convinient way.. The Ruby Documenting Tool follows Freedesktop.org and GNOME standards to provide integration with Desktop Environment.

Getting Started

Starting Ruby Documenting Tool

You can start Ruby Documenting Tool in the following ways:

1. Open an ruby source file in Nautilus.

2. Choose Programming Ruby Documenting Tool from the Applications menu.

3. Run rudoto at the prompt in a terminal such as gnome-terminal, or from the Run Application dialogue.

When You Start Ruby Documenting Tool

When you start Ruby Documenting Tool, the following window is displayed.

The Ruby Documenting Tool window contains the following elements:

1. The menus on the menubar contain all of the commands that you need to work with comments in Ruby Documenting Tool.

2. The toolbar contains a subset of the commands that you can access from the menubar.

3. The display area displays tree of classes and their methods, Code preview window, Comment Editor and Comment Preview Window .

In Ruby Documenting Tool, you can perform the same action in several ways. For example, you can open a ruby source file in the following ways:

This manual ruby source files functionality from the menubar.

Usage

To Open A ruby source file

To open a ruby source file, perform the following steps:

1. Choose File Open.

2. In the Open ruby source file dialogue, select the file you want to open.

3. Click Open. Ruby Documenting Tool displays the name of the ruby source file in the titlebar of the window.

To open another ruby source file, choose File Open again. Ruby Documenting Tool opens each file in the same window.

If you try to open a ruby source file with format that Ruby Documenting Tool does not recognise, the application displays an error message.

To Navigate Through a ruby source file

You can navigate through a classes and methods as follows:

1. To view the next item, choose Navigate Next Object.

2. To view the previous item, choose Navigate Previous Object.

3. To view the parent object in the ruby source file, choose Navigate Parent Object.

4. To view the child object in the ruby source file, choose Navigate Child Object.

To Scroll a Page

To display the page contents that are not currently displayed in the display area, use the following methods:

1. Use the arrow keys or space key on the keyboard.

2. Drag the display area by clicking with the middle mouse button somewhere in the ruby source file and then moving the mouse. For example, to scroll down the page, drag the display area upwards in the window.

3. Use the scrollbars on the window.

To Change the Page Size

You can use the following methods to resize a page in the Ruby Documenting Tool display area:

To Edit Comments

To add new comment to method or class or edit existing simply time corresponding text and markup it

To Copy a ruby source file

To copy a file, perform the following steps:

1. Choose File Save a Copy.

2. Type the new filename in the Filename text box in the Save a Copy dialogue.

   If necessary, specify the location of the copied ruby source file. By default, copies are saved in your home directory.

3. Click Save.

To Close a ruby source file

To close a ruby source file, choose File Close.

If the window is the last Ruby Documenting Tool window open, the application exits.

Shortcuts

Below is a list of all shortcuts present in Ruby Documenting Tool:

Ruby Documenting Tool and RDoc project

Below is information how to comment ruby code, that RDoc can form pretty documentation using Ruby Documenting Tool. Paragraphs are lines that share the left margin. Text indented past this margin are formatted verbatim.

Lists are typed as indented paragraphs with:

If the window is the last Ruby Documenting Tool window open, the application exits.

Labeled lists (sometimes called description lists) are typed using square brackets for the label.

[cat] small domestic animal

[+cat+] command to copy standard input

Labeled lists may also be produced by ...

Labeled lists may also be produced by putting a double colon after the label. This sets the result in tabular form, so the descriptions all line up. This was used to create the ‘author’ block at the bottom of this description.

cat:: small domestic animal

+cat+:: command to copy standard input

Headings are entered using equals signs

= Level One Heading

== Level Two Heading

and so on

Rules (horizontal lines) are entered using three or more hyphens.

Rules (horizontal lines) are entered using three or more hyphens.

Non-verbatim text can be marked up:

Names of classes...

Names of classes, source files, and any method names containing an underscore or preceded by a hash character are automatically hyperlinked from comment text to their description.

Hyperlinks to the web

Hyperlinks to the web starting http:, mailto:, ftp:, or www. are recognized. An HTTP url that references an external image file is converted into an inline IMG... . Hyperlinks starting ‘link:’ are assumed to refer to local files whose path is relative to the —op directory.

Hyperlinks can also be of the form label[url], in which case the label is used in the displayed text, and url is used as the target. If label contains multiple words, put it in braces: {multi word label}[url].

RDoc stops processing comments if it finds a comment line containing ‘#—’.

RDoc stops processing comments if it finds a comment line containing ‘#—’. This can be used to separate external from internal comments, or to stop a comment being associated with a method, class, or module. Commenting can be turned back on with a line that starts ‘#++’.

# Extract the age and calculate the

# date-of-birth.

#--

# FIXME: fails if the birthday falls on

# February 29th

#++

# The DOB is returned as a Time object.

def get_dob(person)

...

Comment blocks can contain other directives:

1. :section: title

   Starts a new section in the output. The title following

   :section: is used as the section heading, and the remainder of the comment containing the section is used as introductory text. Subsequent methods, aliases, attributes, and classes will be documented in this section. A :section: comment block may have one or more lines before the :section: directive. These will be removed, and any identical lines at the end of the block are also removed. This allows you to add visual cues such as

   # ----------------------------------------

   # :section: My Section

   # This is the section that I wrote.

   # See it glisten in the noon-day sun.

   # ----------------------------------------

2. call-seq:

   lines up to the next blank line in the comment are treated as the method‘s calling sequence, overriding the default parsing of method parameters and yield arguments.

3. :include:filename

   include the contents of the named file at this point. The file will be searched for in the directories listed by the —include option, or in the current directory by default. The contents of the file will be shifted to have the same indentation as the ’:’ at the start of the :include: directive.

4. :title:text

   Sets the title for the document. Equivalent to the —title command line parameter. (The command line parameter overrides any :title: directive in the source).

5. :enddoc:

   Document nothing further at the current level.

6. :main:name

   Equivalent to the —main command line parameter.

7. :stopdoc: / :startdoc:

   Stop and start adding new documentation elements to the current container. For example, if a class has a number of constants that you don‘t want to document, put a :stopdoc: before the first, and a :startdoc: after the last. If you don‘t specifiy a :startdoc: by the end of the container, disables documentation for the entire class or module.