Salvar como PDF - Deki Wiki Cercomp

Rdoc
Introdução
RDoc, Projetado por Dave Thomas, é um gerador de documentação para a linguagem de programação
Ruby. Ele analisa o código fonte do Ruby, gerando um conjunto estruturado de páginas para módulos,
métodos e classes. Comentários de código podem ser adicionados de maneira natural.
RDoc é útil mesmo se o código fonte nao tiver comentários explícitos. Ele ainda vai analisar as classes,
métodos e módulos e lista-los nos arquivos APIs gerados.
Como gerar
Uma vez instalado, você pode gerar a documentação usando o comando "rdoc" (no windows o comando é
"rdoc.rb").
% rdoc [options]
[names...]
Digite "rdoc --help" para um sumário de opções atualizadas.
As opções são:
--all
include protected and private methods in the output (por padrão somente métodos publicos são
inclusos)
--main name
set the class, module, or file to appear on the index page
--exclude pattern
exclude files and directories matching this pattern from processing
--quiet
do not display progress messages
--one-file
place all the output into a single file
--op dir
set the output directory to dir (the default is the directory "doc")
--opname name
set the output name (has no effect for HTML).
--charset charset
Set the character set for the generated HTML.
--fmt fmt
generate output in a particular format.
Introdução
1
Rdoc
--include dir,...
specify one or more directories to be searched when satifying given. The directory containing the file
currently being processed is always searched.
--inline-source
By default, the source code of methods is shown in a popup. With this option, it's displayed inline.
--show-hash
A name of the form name in a comment is a possible hyperlink to an instance method name. When
displayed, the '#' is removed unless this option is specified
--template name
specify an alternate template to use when generating output (the default is 'standard'). This template
should be in a directory accessible via $: as rdoc/generators/xxxx_template, where 'xxxx' depends on
the output formatter.
--diagram
include diagrams showing modules and classes. This is currently an experimental feature, and may
not be supported by all output templates. You need dot V1.8.6 or later to use the --diagram option
correctly (www.research.att.com/sw/tools/graphviz/)
Comentários
Os comentários em Ruby possuem algumas características particulares. Abaixo estão listadas as principais.
1. Para gerar listas com paragrafos distanciados das margens, digitamos da seguinte maneira:
◦ um '*' ou '-' (para lista com marcador de bolinha).
◦ um digito numérico seguido por um ponto para listas numeradas.
Por exemplo caso queira gerar a lista acima no RDoc, basta comentar da seguinte maneira:
1. Para gerar listas com paragrafos distanciados das margens,
digitamos da seguinte maneira:
* um '*' ou '-' (para lista com marcador de bolinha).
* um digito numérico seguido por um ponto para listas
numeradas.
2. Lista rotulada (tambem conhecida como lista de descrição) é feita utilizando colchetes no nome do
rótulo (etiqueta).
[gato]
pequeno animal doméstico
[+gato+] comando para copiar a entrada padrão
3. Listas rotuladas tambem podem ser produzidas colocando dois pontos duplos depois do rótulo. O
resultado é em forma tabulada com as descrições todas alinhadas.
gato::
pequeno animal doméstico
+gato+:: comando para copiar entrada padrão
Comentários
2
Rdoc
4. Cabeçalhos são feitos usando sinais de igual
= Cabeçalho de level 1
== Cabeçalho de level 2
e assim por diante
5. Para criar linhas horizontais coloque três ou mais hífens.
6. Partes do texto podem ser diferenciadas da seguinte maneira:
italic:
word ou <em>text</em>
bold:
word ou <b>text</b>
typewriter:
word ou <tt>text</tt>
Para que um comando nao seja interpretado basta adicionar uma barra invertida "\" antes do
comando, como exemplo podemos mostrar como foi gerada a tabela acima.
_italic_::
\_word_ ou \<em>text</em>
*bold*::
\*word* ou \<b>text</b>
+typewriter+:: \+word+ ou \<tt>text</tt>
7. Nomes de classes, arquivos fonte, e qualquer nome de método que esteja sublinhado ou é precedido
de # recebem automaticamente um link para o seu descritor.
8. 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.
9. Method parameter lists are extracted and displayed with the method description. If a method calls
yield, then the parameters passed to yield will also be displayed:
def fred
...
yield line, address
This will get documented as
fred() { |line, address| ... }
You can override this using a comment containing ':yields: ...' immediately after the method
definition
Comentários
3
Rdoc
def fred
# :yields: index, position
...
yield line, address
which will get documented as
fred() { |index, position| ... }
10. ':yields:' is an example of a documentation modifier. These appear immediately after the start of
the document element they are modifying. Other modifiers include
:nodoc:[all]
don't include this element in the documentation. For classes and modules, methods, aliases,
and attributes directly within the affected class will also be omitted. By default, though,
modules and classes within that class of module will be documented. This is turned off by
adding the all modifier.
module SM #:nodoc:
class Input
end
end
module Markup #:nodoc: all
class Output
end
end
In the above code, only class SM::Input will be documented.
:doc:
force a method to be documented even if it wouldn't otherwise be. Useful is, for example, you
want to include documentation of a particular private method.
:notnew:
only applicable to the initialize instance method. Normally RDoc assumes that the
documentation and parameters for initialize are actually for the ::new method, and so fakes
out a ::new for the class. THe :notnew: modifier stops this. Remember that initialize is
protected, so you won't see the documentation unless you use the -a command line option.
11. 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.
Comentários
4
Rdoc
def get_dob(person)
...
12. Comment blocks can contain other directives:
: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.
: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).
:main:name
Equivalent to the --main command line parameter.
Exemplo
Acompanhe o exemplo abaixo:
#
#
#
#
#
#
#
#
#
#
The program takes an initial word or phrase from
the command line (or in the absence of a
parameter from the first line of standard
input). In then reads successive words or
phrases from standard input and reports whether
they are angrams of the first word.
#
#
#
#
This class holds the letters in the original
word or phrase. The is_anagram? method allows us
to test if subsequent words or phrases are
anagrams of the original.
Author::
Dave Thomas (mailto:[email protected])
Copyright:: Copyright (c) 2002 The Pragmatic Programmers, LLC
License::
Distributes under the same terms as Ruby
class Anagram
# Remember the letters in the initial word
def initialize(text)
@initial_letters = letters_of(text)
end
# Test to see if a new word contains the same
# letters as the original
def is_anagram?(text)
@initial_letters == letters_of(text)
Exemplo
5
Rdoc
end
#
#
#
#
#
#
#
Determine the letters in a word or phrase
*
*
*
*
*
all letters are converted to lower case
anything not a letter is stripped out
the letters are converted into an array
the array is sorted
the letters are joined back into a string
def letters_of(text)
text.downcase.delete('^a-z').split('').sort.join
end
end
tester = Anagram.new(ARGV.shift || gets)
ARGF.each do |text|
puts "Anagram! " if tester.is_anagram? text
end
Agora basta digitar o comando abaixo para gerar a documentação.
rdoc --main app/controllers -o manual
Referências
[0] http://en.wikipedia.org/wiki/RDoc
Referências
6