Tdoc

WARNING: As of version 0.11.0 Tdoc contains an rdoc/discover file which parses .rdoc files by default. I am not aware of any issues that this causes but I haven’t tested it with any complex rdoc. So, for now, if your rdoc executable is behaving in an unexpected way, remove this gem and try it again. If it works, please file a bug report. If it doesn’t, then it’s not my fault :).

Test oriented documentation

Tdoc takes a single argument specifying the file or glob to be processed. If no arguments are given, Tdoc will process “README.rdoc” in the working directory.

  • Tdoc will map each file given to a Test::Unit::TestCase.

  • For each such file, named e.g. ‘filename.rdoc’, Tdoc will:

    • require ‘filename.rb’ if it exists

    • create a context within the test case for each file in the directory named ‘filename’ if it exists.

    • process all :include: directives as follows:

      • If the included file has a .rb extention, it will be required in the context of the test case

      • If it has a .rdoc extention it will map to a context within the test case

  • In addition to ‘:include:’, Tdoc understands the following directives:

    • example(s): - Text between these directives maps to a Shoulda #should block

      • within each examples block, Tdoc will convert cut and pastes from irb into assert_equal blocks, so

        >> "asdf"
        => "asdf"
        

        turns into:

        assert_equal "asdf","asdf"
        

    Tdoc will then include all assertions within the context created from the example block

    • setup/end - The first setup/end block is passed to the context’s setup method

usage:

tdoc [file_glob]

setup

@foo='bar'

end

The text between the horizontal lines is included with the ‘:include:’ directive from rdoc/example.rdoc:


:include:rdoc/example.rdoc


Now we are back in the README.rdoc file.

example:

>> @foo
=> "bar"