Was this page helpful?

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.
    --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
      

       

    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

         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.
      
          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.
           #
           # Author::    Dave Thomas  (mailto:dave@x.y)
           # Copyright:: Copyright (c) 2002 The Pragmatic Programmers, LLC
           # License::   Distributes under the same terms as Ruby
    
           # 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.
    
           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)
             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

    Was this page helpful?
    Marcadores (Editar marcadores)
    • No tags
    Páginas com link aqui
    Estatísticas da página
    4929 view(s), 6 edit(s) and 11558 character(s)

    Comentários

    Faça o login para escrever um comentário.

    Anexar arquivo

    Anexos