Как документировать файл с помощью RDoc - PullRequest
Новая
       47

Как документировать файл с помощью RDoc

0 голосов
/ 11 мая 2018

После поиска в документации RDoc Я не могу найти способ документировать файл / метод верхнего уровня в RDoc ...

Предположим, у меня есть следующий код: 

## 
# File documentation.
# File:: foo.rb
# Date:: 09/05/2018
##
require 'stuff'

##
# Class documentation
class Foo
     # Stuff
end

##
# Method documentation
def foo_method()
    # Stuff too
end

Запуск RDoc с этим кодом создаст документацию только для класса Foo, где я хотел бы иметь документацию для файла foo.rb и для метода верхнего уровня foo_method ().

Итакмой вопрос: Как я могу сделать RDoc документирование файлов и метод верхнего уровня?

1 Ответ

0 голосов
/ 15 мая 2018

Все еще не могу найти, как это сделать.

В качестве обходного пути я создал скрипт Ruby, который читает мои другие файлы Ruby (содержащие документацию), анализирует его и создает некоторый модуль макета, куда я вставляю проанализированную документацию.

Вот сценарий, если кто-то когда-либо заинтересовался: 

#:stopdoc:
FILES = ['features/step_definitions/*.rb', 'features/support/*.rb', 'lib/ffi/*.rb', 'lib/*.rb']

FILE_NAME = 'docs/files.rb'
TOP_LEVEL_NAME = 'docs/top_level.rb'

def gen_files(content)
    match = content.scan(/(##[^`]+File::[ ]*([\w]+)[^`]+?##)/)
    File.open(FILE_NAME, 'a') do |f|
        f << "\n"
        f << match[0][0]
        f << "\n"
        f << "module #{match[0][1].capitalize}\n\nend\n"
    end
end

def gen_top_level(content)
    match = content.scan(/(##[\t ]*[\r]*\n(#[^\r\n]*[\r\n\t ]*)*##[\t ]*[\r]*\n){1}([^\r\n]+)/)
    File.open(TOP_LEVEL_NAME, 'a') do |f|
        match[1 .. -1].each do |m|      # Skip the file description
            f << "\n"
            next if (m[2].include?('module') || m[2].include?('class'))
            f << m[0]
            name = nil
            unless m[2].scan(/def [^`]+/).empty?
                name = m[2]
                name = "#{name}\n\nend"
            end
            name = m[2] unless m[2].scan(/[A-Z_]+[ ]?=[ ]?[^`]+/).empty?
            if name.nil?
                name = m[2].gsub(/do([^`]*)/, '').gsub(/[^\d|\w]/, '_').gsub(/_+/, '_').gsub(/_$/, '')
                name = "def #{name}\n\nend"
            end
            f << name
            f << "\n"
        end
    end
end

File.write(FILE_NAME, "module Files #:nodoc:\n\n\n")
File.write(TOP_LEVEL_NAME, "module TopLevel\n\n\n")

FILES.each do |file_regex|
    Dir.glob(file_regex).each do |rb_f|
        gen_files(File.read(rb_f))
        gen_top_level(File.read(rb_f))
    end
end

File.open(FILE_NAME, 'a') do |f|
    f << "\n\n\nend"
end
File.open(TOP_LEVEL_NAME, 'a') do |f|
    f << "\n\n\nend"
end
#:startdoc:

В этом сценарии я создаю 2 файла: один содержит документацию по файлам, другой - документацию верхнего уровня. Для документации верхнего уровня этот скрипт обрабатывает константы, определения методов и шаги Cucumber (Gherkin).

Я все еще немного ошеломлен тем, что такой инструмент, как RDoc, не может указать опцию или что-то для анализа документации функции верхнего уровня ..

Я не приму мой ответ, так как это просто не чистый обходной путь

...