RDoc

Last updated • 1 min readFrom Wikipedia, The Free Encyclopedia
RDoc
Original author(s) Dave Thomas
Stable release
5.1.0 / February 24, 2017;6 years ago (2017-02-24)
Repository
Written in Ruby
Operating system Cross-platform
Type embedded documentation generator
License GPLv2
Website ruby.github.io/rdoc/

RDoc, designed by Dave Thomas, is an embedded documentation generator for the Ruby programming language. It analyzes Ruby source code, generating a structured collection of pages for Ruby objects and methods. Code comments can be added in a natural style. RDoc is included as part of the Ruby core distribution. The RDoc software and format are successors to the Ruby Document format (with associated software RD).

Contents

RDoc can produce usable documentation even if the target source code does not contain explicit comments as it will still parse the classes, modules, and methods, and list them in the generated API files. RDoc also provides the engine for creating Ruby ri data files, providing access to API information from the command line.

RDoc and ri are currently maintained by Eric Hodel and Ryan Davis.

Syntax

RDoc supports four markup languages, RDoc Markup, Markdown, tomdoc, and rdtool. Its own RDoc Markup is used by default. In RDoc Markup, special directives are enclosed in a pair of colons. For example, to indicate that a method takes arguments called site and article, one can write :args: site, article. [1]

See also

Related Research Articles

YAML(see § History and name) is a human-readable data serialization language. It is commonly used for configuration files and in applications where data is being stored or transmitted. YAML targets many of the same communications applications as Extensible Markup Language (XML) but has a minimal syntax which intentionally differs from Standard Generalized Markup Language (SGML). It uses both Python-style indentation to indicate nesting, and a more compact format that uses [...] for lists and {...} for maps but forbids tab characters to use as indentation thus only some JSON files are valid YAML 1.2.

<span class="mw-page-title-main">Doxygen</span> Free software for generating software documentation from source code

Doxygen is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxygen uses its parse tree to generate diagrams and charts of the code structure. Doxygen can cross reference documentation and code, so that the reader of a document can easily refer to the actual code.

reStructuredText is a file format for textual data used primarily in the Python programming language community for technical documentation.

A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to write using any generic text editor and easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output.

Javadoc is a documentation generator created by Sun Microsystems for the Java language for generating API documentation in HTML format from Java source code. The HTML format is used for adding the convenience of being able to hyperlink related documents together.

The following tables compare general and technical information for a number of documentation generators. Please see the individual products' articles for further information. Unless otherwise specified in footnotes, comparisons are based on the stable versions without any add-ons, extensions or external programs. Note that many of the generators listed are no longer maintained.

A documentation generator is a programming tool that generates software documentation intended for programmers or end users, or both, from a set of source code files, and in some cases, binary files. Some generators, such as Javadoc, can use special comments to drive the generation. Doxygen is an example of a generator that can use all of these methods.

<span class="mw-page-title-main">Markdown</span> Plain text markup language

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004 as a markup language that is easy to read in its source code form. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.

Ddoc is a compiler-embedded documentation generator and associated syntax, for the D programming language, designed by Walter Bright. Its emphasis is on being able to write documentation in code comments in a natural style, minimizing the need for embedded markup and thus improving the legibility of the code comments. It is similar in concept to Doxygen and Javadoc.

Embedded Ruby is a templating system that embeds Ruby into a text document. It is often used to embed Ruby code in an HTML document, similar to ASP and JSP, and PHP and other server-side scripting languages. The templating system of eRuby combines Ruby code and plain text to provide flow control and variable substitution, thus making the combined code easier to maintain.

Sandcastle is a documentation generator from Microsoft. It automatically produces MSDN-style code documentation out of reflection information of .NET assemblies and XML documentation comments found in the source code of these assemblies. It can also be used to produce user documentation from Microsoft Assistance Markup Language (MAML) with the same look and feel as reference documentation.

<span class="mw-page-title-main">NDoc</span>

NDoc is a code documentation generator for the Common Language Infrastructure created by Jason Diamond, Jean-Claude Manoli and Kral Ferch. It is licensed under the GNU General Public License.

<span class="mw-page-title-main">Comment (computer programming)</span> Explanatory note in the source code of a computer program

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters. The syntax of comments in various programming languages varies considerably.

Information Presentation Facility (IPF) is a system for presenting online help and hypertext on IBM OS/2 systems. IPF also refers to the markup language that is used to create IPF content. The IPF language has its origins in BookMaster and Generalized Markup Language developed by IBM. The IPF language is very similar to the well-known HTML language, version 3.0, with a range of additional possibilities. Therefore, a trained user may use virtually any word processor when creating IPF documents. The IPF language consists of 45 basic commands.

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.

<span class="mw-page-title-main">VSdocman</span>

VSdocman is a documentation generator that allows for code commenting and the automatic generation of technical documentation from C# and VB .NET projects. It is directly integrated in Visual Studio as an extension.

MakeDoc is a lightweight markup language created in 2000 by Carl Sassenrath for creating documentation and web pages using simple text notations. The language is used extensively in the REBOL community for documentation, websites, and wikis.

YARD, is an embedded documentation generator for the Ruby programming language. It analyzes the Ruby source code, generating a structured collection of pages for Ruby objects and methods. Code comments can be added in a natural style.

The Java Development Kit (JDK) is a distribution of Java Technology by Oracle Corporation. It implements the Java Language Specification (JLS) and the Java Virtual Machine Specification (JVMS) and provides the Standard Edition (SE) of the Java Application Programming Interface (API). It is derivative of the community driven OpenJDK which Oracle stewards. It provides software for working with Java applications. Examples of included software are the virtual machine, a compiler, performance monitoring tools, a debugger, and other utilities that Oracle considers useful for a Java programmer.

LibSBML is an open-source software library that provides an application programming interface (API) for the SBML format. The libSBML library can be embedded in a software application or used in a web servlet as part of the application or servlet's implementation of support for reading, writing, and manipulating SBML documents and data streams. The core of libSBML is written in ISO standard C++; the library provides API for many programming languages via interfaces generated with the help of SWIG.

References

  1. "class RDoc::Markup". rdoc 6.0.4 Documentation.