Documentation

From Rosetta Code
Jump to: navigation, search
Task
Documentation
You are encouraged to solve this task according to the task description, using any language you may know.
Show how to insert documentation for classes, functions, and/or variables in your language. If this documentation is built-in to the language, note it. If this documentation requires external tools, note them.

See Also:

Contents

[edit] Ada

In some ways, Ada is a self documenting language by design. When building packages (the equivalent of modules in python), you have to create two separate files: a spec and a body. The spec resides in a .ads file, and contains the interface to the package that is visible to someone using it.

All functions, procedures and data-types that can be used in other Ada programs have to have an entry in the spec that defines how they are used. The only requirement for the body file is that it give definitions for everything found in the spec. You can also include other functions in the body file to help build the functions defined in the spec. Anything that doesn't appear in the .ads file won't be accessible to a programmer who uses that particular package.

The ada spec file gives you all the information you need to know to effectively use the functions in that package, and as such is the primary documentation that you want to look at. If you have the .adb and .ads files physically available to you, you can also verify that the information is correct by re-compiling the package, the Ada compiler checks to make sure that the spec and the body agree, and that everything defined in the spec is implemented in the body.

Example ADS file for instrumenting sorting functions:

with Ada.Text_Io; use Ada.Text_Io;
 
generic
SortName : in String;
type DataType is (<>);
type SortArrayType is array (Integer range <>) of DataType;
with procedure Sort (SortArray : in out SortArrayType;
Comp, Write, Ex : in out Natural);
 
package Instrument is
-- This generic package essentially accomplishes turning the sort
-- procedures into first-class functions for this limited purpose.
-- Obviously it doesn't change the way that Ada works with them;
-- the same thing would have been much more straightforward to
-- program in a language that had true first-class functions
 
package Dur_Io is new Fixed_Io(Duration);
 
procedure TimeSort (Arr : in out SortArrayType);
 
procedure Put;
 
procedure Put (File : in out File_Type);
 
end Instrument;

There is also a tool called AdaDoc. This can be used to generate documentation of an Ada module (or modules?) for a variety of different formats: HTML, LaTeX, plain text and more.

[edit] AutoHotkey

You can use the GenDocs library.
It generates html documentation in the style of the canonical ahk documentation.
BBCode is supported for markup.

Example from the library distribution:
;
; Function: example_add
; Description:
; Adds two or three numbers (see [url=http://en.wikipedia.org/Number]Number [/url])
; Syntax: example_add(number1, number2[, number3=0])
; Parameters:
; number1 - First number to add.
; number2 - Second number to add.
; number3 - (Optional) Third number to add. You can just omit this parameter.
; Return Value:
; sum of parameters
; Example:
; MsgBox % example_add(example_add(2, 3, 4), 5)
;
example_add(number1, number2, number3=0){
return number1 + number2 + number3
}
Resulting Documentation

[edit] C

A common tool for generating documentation is Doxygen:

/**
* \brief Perform addition on \b a and \b b.
*
* \param int One of the numbers to be added.
* \param int Another number to be added.
* \return The sum of \b a and \b
* \code
* int sum = add(1, 2)
* \endcode
*/

int add(int a, int b) {
return a + b;
}
 

[edit] Clojure

(def 
#^{:doc "Metadata can contain documentation and can be added to vars like this."}
test1)
 
(defn test2
"defn and some other macros allow you add documentation like this. Works the same way"
[])

[edit] Common Lisp

Common Lisp allows the definition of documentation strings for functions, variables, classes, ... It also allows retrieval of documentation strings.

CL-USER 83 > (defun add (a b)
               "add two numbers a and b"
               (+ a b))
ADD
CL-USER 84 > (documentation 'add 'function)
"add two numbers a and b"
CL-USER 85 > (defvar *color* :green "the output color symbol")
*COLOR*
CL-USER 86 > (documentation '*color* 'variable)
"the output color symbol"
CL-USER 87 > (defclass person ()
               ((age :documentation "the age of the person"))
               (:documentation "the person class"))
#<STANDARD-CLASS PERSON 402005BCBB>
CL-USER 88 > (documentation 'person 'type)
"the person class"

[edit] C#

This documentation method will work perfectly with the built in object browser in Visual Studio. The object browser can then show detailed information for each component. To make documentation that can be parsed, a triple slash (///) must be used. Further information can be found in this tutorial. A list of available xml elements for use in documentation is here.

/// <summary>
/// The XMLSystem class is here to help handle XML items in this site.
/// </summary>
public static class XMLSystem
{
static XMLSystem()
{
// Constructor
}
 
/// <summary>
/// A function to get the contents of an XML document.
/// </summary>
/// <param name="name">A valid name of an XML document in the data folder</param>
/// <returns>An XmlDocument containing the contents of the XML file</returns>
public static XmlDocument GetXML(string name)
{
return null;
}
}

[edit] D

D compiler comes with a builtin documentation system called Ddoc. Alternative systems may be used (a common alternative is Doxygen which includes some D support).

/**
This is a documentation comment for someFunc and someFunc2.
$(DDOC_COMMENT comment inside a documentation comment
(results in a HTML comment not displayed by the browser))
 
Header:
content (does not need to be tabbed out; this is done for clarity
of the comments and has no effect on the resulting documentation)
 
Params:
arg1 = Something (listed as "int <i>arg1</i> Something")
arg2 = Something else
 
Returns:
Nothing
 
TODO:
Nothing at all
 
BUG:
None found
*/

void someFunc(int arg1, int arg2) {}
 
// This groups this function with the above (both have the
// same doc and are listed together)
/// ditto
void someFunc2(int arg1, int arg2) {}
 
/// Sum function.
int sum(in int x, in int y) pure nothrow {
return x + y;
}
 
// These unittests will become part of sum documentation:
///
unittest {
assert(sum(2, 3) == 5);
}
 
/++ Another documentation comment +/
void main() {}

[edit] Delphi

XML comments are shown in the IDE and is included in the XML documentation produced by the compiler when using --docs.

type
/// <summary>Sample class.</summary>
TMyClass = class
public
/// <summary>Converts a string into a number.</summary>
/// <param name="aValue">String parameter</param>
/// <returns>Numeric equivalent of aValue</returns>
/// <exception cref="EConvertError">aValue is not a valid integer.</exception>
function StringToNumber(aValue: string): Integer;
end;

[edit] E

E's documentation facilities outside of comments are directly inspired by Javadoc and use a similar basic syntax; however, they are part of the language rather than being an idiom about using comments.

Objects, methods, and functions have doc-comments (much as in Python or Common Lisp); the syntax for them is /** ... */ immediately preceding the definition of the object, method, or function. (Note that E does not recognize the /*...*/ comment syntax in general.)

The documentation syntax is in some ways underdefined: there is no layer which discards the leading '*'s as in Javadoc, so the documentation string contains all leading indentation (which is problematic for the source prettyprinter), and there is no formal definition yet of the syntax used within the doc-comments.

? /** This is an object with documentation */
> def foo {
> # ...
> }
# value: <foo>
 
? foo.__getAllegedType().getDocComment()
# value: " This is an object with documentation "

Variables may not have doc-comments, because they are never part of the public interface of an object.

[edit] Eiffel

The Eiffel language was designed with a goal of producing documentation directly from software text. Certain comments, contracts for publicly accessible routines, and the class invariant are all extracted into the documentation views of a class.

The following is a simple class written in Eiffel:

note
description: "Objects that model Times of Day: 00:00:00 - 23:59:59"
author: "Eiffel Software Construction Students"
 
class
TIME_OF_DAY
create
make
 
feature -- Initialization
 
make
-- Initialize to 00:00:00
do
hour := 0
minute := 0
second := 0
ensure
initialized: hour = 0 and
minute = 0 and
second = 0
end
 
feature -- Access
 
hour: INTEGER
-- Hour expressed as 24-hour value
 
minute: INTEGER
-- Minutes past the hour
 
second: INTEGER
-- Seconds past the minute
 
feature -- Element change
 
set_hour (h: INTEGER)
-- Set the hour from `h'
require
argument_hour_valid: 0 <= h and h <= 23
do
hour := h
ensure
hour_set: hour = h
minute_unchanged: minute = old minute
second_unchanged: second = old second
end
 
set_minute (m: INTEGER)
-- Set the minute from `m'
require
argument_minute_valid: 0 <= m and m <= 59
do
minute := m
ensure
minute_set: minute = m
hour_unchanged: hour = old hour
second_unchanged: second = old second
end
 
set_second (s: INTEGER)
-- Set the second from `s'
require
argument_second_valid: 0 <= s and s <= 59
do
second := s
ensure
second_set: second = s
hour_unchanged: hour = old hour
minute_unchanged: minute = old minute
end
 
feature {NONE} -- Implementation
 
protected_routine
-- A protected routine (not available to client classes)
-- Will not be present in documentation (Contract) view
do
 
end
 
invariant
 
hour_valid: 0 <= hour and hour <= 23
minute_valid: 0 <= minute and minute <= 59
second_valid: 0 <= second and second <= 59
 
end -- class TIME_OF_DAY

Below is the Contract (documentation) view of the same class. It is the view that potential reuse consumers would reference when writing clients.

note
description: "Objects that model Times of Day: 00:00:00 - 23:59:59"
author: "Eiffel Software Construction Students"
 
class interface
TIME_OF_DAY
 
create
make
 
feature -- Initialization
 
make
-- Initialize to 00:00:00
ensure
initialized: hour = 0 and minute = 0 and second = 0
 
feature -- Access
 
hour: INTEGER_32
-- Hour expressed as 24-hour value
 
minute: INTEGER_32
-- Minutes past the hour
 
second: INTEGER_32
-- Seconds past the minute
 
feature -- Element change
 
set_hour (h: INTEGER_32)
-- Set the hour from `h'
require
argument_hour_valid: 0 <= h and h <= 23
ensure
hour_set: hour = h
minute_unchanged: minute = old minute
second_unchanged: second = old second
 
set_minute (m: INTEGER_32)
-- Set the minute from `m'
require
argument_minute_valid: 0 <= m and m <= 59
ensure
minute_set: minute = m
hour_unchanged: hour = old hour
second_unchanged: second = old second
 
set_second (s: INTEGER_32)
-- Set the second from `s'
require
argument_second_valid: 0 <= s and s <= 59
ensure
second_set: second = s
hour_unchanged: hour = old hour
minute_unchanged: minute = old minute
 
invariant
hour_valid: 0 <= hour and hour <= 23
minute_valid: 0 <= minute and minute <= 59
second_valid: 0 <= second and second <= 59
 
end -- class TIME_OF_DAY

It is important to notice what is missing from this view. It shows only the specification of the class. The implementations of routines and any routines which are not public are not visible. The notes and comments, public features (including contracts for routines), and the class invariant all remain as components of the specification.

This view was produced by EiffelStudio which also supports an Interface view which is similar to the Contract view above, but also includes contracts for any inherited routines, and the complete inherited class invariant. EiffelStudio can publish these and other documentation view in HTML and other formats suitable for sharing.

[edit] Erlang

Erlang has Edoc. From the documentation: "EDoc is the Erlang program documentation generator. Inspired by the Javadoc(TM) tool for the Java(TM) programming language, EDoc is adapted to the conventions of the Erlang world, and has several features not found in Javadoc."

It is also possible to document functions and their arguments with type information. These can be used by Dialyzer. From the documentation: "The Dialyzer is a static analysis tool that identifies software discrepancies such as definite type errors, code which has become dead or unreachable due to some programming error, unnecessary tests, etc. in single Erlang modules or entire (sets of) applications."

[edit] Factor

Factor has an extensive documentation system built in. See docs.factorcode.org : [1]

[edit] Fancy

def class Foo {
"""
This is a docstring. Every object in Fancy can have it's own docstring.
Either defined in the source code, like this one, or by using the Object#docstring: method
"""
def a_method {
"""
Same for methods. They can have docstrings, too.
"""
}
}
Foo docstring println # prints docstring Foo class
Foo instance_method: 'a_method . docstring println # prints method's docstring

[edit] Go

Go source has both single line and block comments.

Godoc is an external command that extracts documentation from source code and outputs it as text or serves it as HTML. Godoc extracts exported top-level declarations and comments that preceede them. To be extracted, comments must immediately preceed the declaration with no intervening blank line. Godoc may or may not reformat comments, depending on output options, but it does this in a general way and there are no markup rules to follow.

Example code demonstrating what godoc extracts and what it doesn't:

// Example serves as an example but does nothing useful.
//
// A package comment preceeds the package clause and explains the purpose
// of the package.
package example
 
// Exported variables.
var (
// lookie
X, Y, Z int // popular names
)
 
/* XP does nothing.
 
Here's a block comment. */

func XP() { // here we go!
// comments inside
}
 
// Non-exported.
func nonXP() {}
 
// Doc not extracted.
 
var MEMEME int

Text output of godoc: (HTML looks nicer, of course)

PACKAGE

package example
import "."

Example serves as an example but does nothing useful.

A package comment preceeds the package clause and explains the purpose
of the package.


VARIABLES

var MEMEME int

var (
    // lookie
    X, Y, Z int // popular names
)
Exported variables.


FUNCTIONS

func XP()
 XP does nothing.

Here's a block comment.

[edit] Haskell

Haddock is a popular documentation generator for the Haskell language.

-- |This is a documentation comment for the following function
square1 :: Int -> Int
square1 x = x * x
 
-- |It can even
-- span multiple lines
square2 :: Int -> Int
square2 x = x * x
 
square3 :: Int -> Int
-- ^You can put the comment underneath if you like, like this
square3 x = x * x
 
{-|
Haskell block comments
are also supported
-}

square4 :: Int -> Int
square4 x = x * x
 
-- |This is a documentation comment for the following datatype
data Tree a = Leaf a | Node [Tree a]
 
-- |This is a documentation comment for the following type class
class Foo a where
bar :: a

See this chapter for more information about the markup.

[edit] Icon and Unicon

[edit] Icon

There are no formal conventions for documentation built into the Icon/Unicon. However, there are conventions for the different libraries that are supported by automation.

############################################################################
#
# File: filename.icn
#
# Subject: Short Description
#
# Author: Author's name
#
# Date: Date
#
############################################################################
#
# This file is in the public domain. (or other license)
#
############################################################################
#
# Long form docmentation
#
############################################################################
#
# Links:
#
############################################################################
 
procedure x1() #: short description of procedure
 
  • ipldoc.icn Program to collect library documentation.
  • iplindex.icn Program to produce indexed listing of the program library.


[edit] Unicon

XYZ
This example is in need of improvement:
Needs corresponding Unilib formats

TBD

[edit] J

Use scripdoc:

NB. =========================================================
NB.*apply v apply verb x to y
apply=: 128!:2
 
NB. =========================================================
NB.*def c : (explicit definition)
def=: :
 
NB.*define a : 0 (explicit definition script form)
define=: : 0
 
NB.*do v name for ".
do=: ".
 
NB.*drop v name for }.
drop=: }.
 
Note 1
Note accepts multi-line descriptions.
Definitions display the source.
)

 
usleep
3 : '''libc.so.6 usleep > i i''&(15!:0) >.y'
 

[edit] Java

Documentation is typically given using Javadoc comments. Documentation is generated from these comments using the Javadoc tool. The default output (from the standard doclet) takes the form of an HTML page with frames, so HTML is frequently embedded in the comments. The comments all start with /**, end with */, and usually have "tags" embedded starting with @.

/**
* This is a class documentation comment. This text shows at the top of the page for this class
* @author Joe Schmoe
*/

public class Doc{
/**
* This is a field comment for a variable
*/

private String field;
 
/**
* This is a method comment. It has parameter tags (param), an exception tag (throws),
* and a return value tag (return).
*
* @param num a number with the variable name "num"
* @throws BadException when something bad happens
* @return another number
*/

public int method(long num) throws BadException{
//...code here
}
}

[edit] Logtalk

Logtalk provides a set of entity and predicate documenting directives. The content of these and other directives can be retrieved using the language reflection features. A companion tool, "lgtdoc", uses the reflection API to extract the documenting information and export it as XML files and provides a set of stylesheets to convert these file to e.g. HTML and PDF files.

 
:- object(set(_Type),
extends(set)).
 
% the info/1 directive is the main directive for documenting an entity
% its value is a list of Key-Value pairs; the set of keys is user-extendable
:- info([
version is 1.2,
author is 'A. Coder',
date is 2013/10/13,
comment is 'Set predicates with elements constrained to a single type.',
parnames is ['Type']
]).
 
% the info/2 directive is the main directive for documenting predicates
% its second value is a list of Key-Value pairs; the set of keys is user-extendable
:- public(intersection/3).
:- mode(intersection(+set, +set, ?set), zero_or_one).
:- info(intersection/3, [
comment is 'Returns the intersection of Set1 and Set2.',
argnames is ['Set1', 'Set2', 'Intersection']
]).
 
...
 
:- end_object.
 

[edit] Mathematica

Mathematica inline documentation can be accessed directly in the code by pressing F1. No external tools required

f[x_,y_] := x + y (* Function comment : adds two numbers *)
f::usage = "f[x,y] gives the sum of x and y"
 
?f
-> f[x,y] gives the sum of x and y


[edit] Objective-C

Common tools include [Doxygen http://doxygen.org], [HeaderDoc http://developer.apple.com/mac/library/documentation/DeveloperTools/Conceptual/HeaderDoc/intro/intro.html] and GSDoc. The use of doxygen is much like in C.

[edit] HeaderDoc

/*!
@function add
@abstract Adds two numbers
@discussion Use add to sum two numbers.
@param a an integer.
@param b another integer.
@return the sum of a and b
*/
int add(int a, int b) {
return a + b;
}

[edit] OCaml

OCamldoc is a documentation generator that is included with OCaml. Documentation comments all start with (** (but no more than two asterisks) and end with *). Like Javadoc, "tags" can be embedded starting with @.

[edit] PARI/GP

The primary method for documenting GP functions is the addhelp() command:

addhelp(funcName, "funcName(v, n): This is a description of the function named funcName.");

PARI documentation is done as for C.

[edit] Perl

Perl's documentation mechanism is called POD (Plain Old Documentation). Basically, any line that starts with an equal sign followed by a word (e.g. =head1) starts a documentation comment; and it lasts until a line that begins with =cut. Many formatting commands are recognized; for example, a line beginning with =item starts a section for an item, text wrapped in I< ... > is italicized, text wrapped in C< ... > is formatted as code, etc. See the perlpod and perlpodspec manuals for more details about the format.

[edit] Perl 6

Similarly to Perl 5, Perl 6 is documented using Pod (a redesigned version of POD). However, it's not simply ignored by the parser as in Perl 5, it's an internal part of the language spec and can be used to attach documentation objects to almost any part of the code.

#= it's yellow
sub marine { ... }
say &marine.WHY; # "it's yellow"
 
#= a shaggy little thing
class Sheep {
#= not too scary
method roar { 'roar!' }
}
say Sheep.WHY; # "a shaggy little thing"
say Sheep.^find_method('roar').WHY; # "not too scary"

A compiler has a built-in --doc switch that will generate documentation from a given source file.

[edit] PHP

phpDocumentor (phpdoc) is a documentor for PHP. The syntax is similar to Javadoc.

[edit] PicoLisp

PicoLisp doesn't yet support inline documentation directly in the code. However, it has built-in runtime documentation via the 'doc' function. This requires no external tools, except that the interpreter must have been started in debug mode.

: (doc 'car)         # View documentation of a function
 
: (doc '+Entity) # View documentation of a class
 
: (doc '+ 'firefox) # Explicitly specify a browser

[edit] PureBasic

; This is a small demo-code to demonstrate PureBasic’s internal
; documentation system.
 
;- All Includes
; By starting the line with ‘;-‘ marks that specific line as a special comment,
; and this will be included in the overview, while normal comments will not.
 
IncludeFile "MyLibs.pbi"
IncludeFile "Combustion_Data.pbi"
 
;-
;- Start of functions and Macros
;- Engeneering stuff
 
; A small function to calculate gas properties
Procedure.f CalcR( p.f, V.f, T.f)
ProcedureReturn p*V/T
EndProcedure
 
; Example of a Macro
; These are indicated by '+' in the overview
Macro HalfPI()
(#PI/2)
EndMacro
 
;-
;- - - - - - - - - - -
;- IO-Functions
 
Procedure Write_and_Close( File, Text$)
If IsFile(File)
WriteString(File,Text$)
CloseFile(file)
EndIf
EndProcedure

This would as an example be shown in the code over view as the picture below.

PureBasic Procedure overview.png

[edit] Python

A string literal which is the first expression in a class, function, or module definition is called a docstring. It can be subsequently accessed at runtime using the .__doc__ attribute of the class, function, or module.

class Doc(object):
"""
This is a class docstring. Traditionally triple-quoted strings are used because
they can span multiple lines and you can include quotation marks without escaping.
"""

def method(self, num):
"""This is a method docstring."""
pass

pydoc, a module of the Python standard library, can automatically generate documentation gleaned from docstrings of modules. The documentation can be presented as pages of text on a terminal; automatically served to a Web Browser; or saved as HTML. The command line pydoc command , in addition, can display docstring information in a TK based GUI browser.

The built-in help() function uses the pydoc module to display docstring information at the command prompt of the Python interactive shell.

>>> def somefunction():
"takes no args and returns None after doing not a lot"
 
 
>>> help(somefunction)
Help on function somefunction in module __main__:
 
somefunction()
takes no args and returns None after doing not a lot
 
>>>

[edit] Sphinx

The Sphinx Documentation generator suite is used to generate the new Python documentation.

[edit] R

R objects are documented in files written in "R documentation" (Rd) format, which is similar to LaTeX markup. See Chapter 2 of Writing R Extensions for the full details. Example function document files can be created using

example(package.skeleton)

An example documentation file for a function 'f', taking arguments 'x' and 'y' is

\name{f}
\Rdversion{1.1}
\alias{f}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
%% ~~function to do ... ~~
}
\description{
%% ~~ A concise (1-5 lines) description of what the function does. ~~
}
\usage{
f(x, y)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{x}{
%% ~~Describe \code{x} here~~
}
\item{y}{
%% ~~Describe \code{y} here~~
}
}
\details{
%% ~~ If necessary, more details than the description above ~~
}
\value{
%% ~Describe the value returned
%% If it is a LIST, use
%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}
\references{
%% ~put references to the literature/web site here ~
}
\author{
%% ~~who you are~~
}
\note{
%% ~~further notes~~
}
 
%% ~Make other sections like Warning with \section{Warning }{....} ~
 
\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
##---- Should be DIRECTLY executable !! ----
##-- ==> Define data, use random,
##-- or do help(data=index) for the standard data sets.
 
## The function is currently defined as
function(x,y) x+y
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ ~kwd1 }
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

[edit] Racket

Racket documentation is written in an integrated documentation domain-specific language called Scribble:

 
#lang scribble/manual
(require (for-label "sandwiches.rkt"))
 
@defproc[(make-sandwich [ingredients (listof ingredient?)])
sandwich?]{
Returns a sandwich given the right ingredients.
}
 

Programs can also be written with inline documentation using either the scribble/srcdoc or scribble/lp (literate programming) libraries.

[edit] REBOL

rebol [
Title: "Documentation"
Date: 2009-12-14
Author: oofoe
URL: http://rosettacode.org/wiki/Documentation
Purpose: {To demonstrate documentation of REBOL pograms.}
]

 
; Notice the fields in the program header. The header is required for
; valid REBOL programs, although the fields don't have to be filled
; in. Standard fields are defined (see 'system/script/header'), but
; I can also define other fields as I like and they'll be available
; there.
 
; This is a comment. The semicolon can be inserted anywhere outside of
; a string and will escape to end of line. See the inline comments
; below.
 
; Functions can have a documentation string as the first part of the
; argument definition block. Each argument can specify what types it
; will accept as well as a description. All typing/documentation
; entries are optional. Notice that local variables can be documented
; as well.
 
sum: func [
"Add numbers in block."
data [block! list!] "List of numbers to add together."
/average "Calculate average instead of sum."
/local
i "Iteration variable."
x "Variable to hold results."
] [
x: 0 repeat i data [x: x + i]
either average [x / length? data][x] ; Functions return last result.
]
 
print [sum [1 2 3 4 5 6] crlf sum/average [7 8 9 10] crlf]
 
; The help message is constructed from the public information about
; the function. Internal variable information isn't shown.
 
help sum print ""
 
; The source command provides the source to any user functions,
; reconstructing the documentation strings if they're provided:
 
source sum print ""
 
; This is an object, describing a person, whose name is Bob.
 
bob: make object! [
name: "Bob Sorkopath"
age: 24
hi: func ["Say hello."][print "Hello!"]
]
 
; I can use the 'help' word to get a list of the fields of the object
 
help bob print ""
 
; If I want see the documentation or source for 'bob/hi', I have to
; get a little tricky to get it from the object's namespace:
 
x: get in bob 'hi help x print ""
 
probe get in bob 'hi

Output:

21
8.5

USAGE:
    SUM data /average

DESCRIPTION:
     Add numbers in block.
     SUM is a function value.

ARGUMENTS:
     data -- List of numbers to add together. (Type: block list)

REFINEMENTS:
     /average -- Calculate average instead of sum.

sum: func [
    "Add numbers in block."
    data [block! list!] "List of numbers to add together."
    /average "Calculate average instead of sum."
    /local
    i "Iteration variable."
    x "Variable to hold results."
][
    x: 0 repeat i data [x: x + i]
    either average [x / length? data] [x]
]

BOB is an object of value:
   name            string!   "Bob Sorkopath"
   age             integer!  24
   hi              function! Say hello.


USAGE:
    X

DESCRIPTION:
     Say hello.
     X is a function value.

func ["Say hello."][print "Hello!"]

[edit] Retro

Retro allows for insertion of documentation blocks. The contents of these can be in any format desired, though the standard Retro system uses Restructured Text for all embedded and external documentation.

 
doc{
========
Function: foo
========
 
Stack
----
a1 a2 - b
 
Usage
-----
Adds a1 to a2 returning b.
}doc
 
: foo ( aa-b ) + ;
 


[edit] REXX

[edit] version 1

One technique with REXX is to use in-line documentation as REXX supports the accessing of
the REXX program's source, which can include documentation if properly fenced.

This particular example uses lowercase fences of:

  • <help>
  • </help>

to delineate the documentation. But, any two unique strings could be used.

Note that the documentation is bracketed by the standard REXX comment delimiters to preserve program lexigraphical integrity.

/*REXX program to show how to display embedded documention in REXX code.*/
parse arg doc
doc=space(doc)
if doc=='?' then call help /*show doc if arg is a single  ? */
/*════════════════════════regular═══════════════════════════════════════*/
/*════════════════════════════════mainline══════════════════════════════*/
/*═════════════════════════════════════════code═════════════════════════*/
/*══════════════════════════════════════════════here.═══════════════════*/
exit
 
/*──────────────────────────────────HELP subroutine─────────────────────*/
help: help=0; do j=1 for sourceline()
_=sourceline(j)
if _=='<help>' then do; help=1; iterate; end
if _=='</help>' then exit
if help then say _
end /*j*/
exit /*stick a fork in it, we're done.*/
 
/*──────────────────────────────────start of the in─line documentation.
<help>
To use the YYYY program, enter:
 
 
YYYY numberOfItems
YYYY (with no args for the default)
YYYY  ? (to see this documentation)
 
 
─── where:
 
numberOfItems is the number of items to be processed.
 
If no "numberOfItems" are entered, the default of 100 is used.
</help>
────────────────────────────────────end of the in─line documentation. */

[edit] version 2

/* REXX ***************************************************************
* 13.10.2013 Walter Pachl another way to show documentation
* no tags and good enough if only one documentation block
**********************************************************************/

beghelp=here()+1 /* line where the docmentation begins
Documentation
any test explaining the program's invocaion and workings
---
and where it ends */

endhelp=here()-2
If arg(1)='?' Then Do
Do i=beghelp To endhelp
Say sourceline(i)
End
Exit
End
say 'the program would be here!'
Exit
here: return sigl /* returns the invocation's line number */

[edit] Ruby

RDoc is the de-facto documentation tool that's bundled with Ruby distributions. From it's documentation:

Rdoc is an application that produces documentation for one or more Ruby source files. We work similarly to JavaDoc, parsing the source, and extracting the definition for classes, modules, and methods (along with includes and requires). We associate with these optional documentation contained in the immediately preceding comment block, and then render the result using a pluggable output formatter.

RDoc produces output that looks like this.

Ruby's documentation comments look like Perl's PODs. Translating Java's example:

=begin rdoc
RDoc is documented here[http://www.ruby-doc.org/core/classes/RDoc.html].
 
This is a class documentation comment. This text shows at the top of the page
for the class.
 
Comments can be written inside "=begin rdoc"/"end" blocks or
in normal '#' comment blocks.
 
There are no '@parameters' like javadoc, but 'name-value' lists can be written:
Author:: Joe Schmoe
Date:: today
=end

 
class Doc
# This is a comment for a Constant
Constant = nil
 
# This is a method comment. Parameters and return values can be named
# with the "call-seq" directive.
#
# call-seq:
# a_method(first_arg, second_arg) -> return_value
#
def a_method(arg1, arg2='default value')
do_stuff
end
 
# Class methods will be shown in a separate section of the generated documentation.
def self.class_method
Constant
end
end
 
# :include:boilerplate.txt

[edit] Smalltalk

(Squeak/Pharo)

 
FooClass comment: 'This is a comment ....'.
 

[edit] Tcl

Documentation for Tcl code is usually prepared in separate files using a tool like doctools, but inline docs (with all their inherent limitations) can be done with the likes of Robodoc. For example:

#****f* RosettaCode/TclDocDemo
# FUNCTION
# TclDocDemo is a simple illustration of how to do documentation
# of Tcl code using Robodoc.
# SYNOPSYS
# TclDocDemo foo bar
# INPUTS
# foo -- the first part of the message to print
# bar -- the last part of the message to print
# RESULT
# No result
# NOTES
# Prints a message based on a template by filling in with the
# supplied strings.
#*****
proc TclDocDemo {foo bar} {
puts [format "%s -- %s" $foo $bar]
}

Both doctools and robodoc can produce output in multiple formats.

[edit] ZX Spectrum Basic

Inline documentation is limited to comments within the code. However, there is no inbuilt extraction tool, so this would need to be written. The example shows how documentation for a variable and a function could be embedded within the code:

 10 LET a=10: REM a is the number of apples
1000 DEF FN s(q)=q*q: REM s is a function that takes a single numeric parameter and returns its square

Alternatively, it is possible to embed documentation into LPRINT statements within a subroutine, allowing the language to print its own documentation. In the example below, the command GOSUB 2000 would print the documentation:

10 GOSUB 2000: REM call a subroutine to print the documentation
1999 STOP
2000 REM Print the documentation
2010 LPRINT "a is the number of apples"
2020 LPRINT "s is a function that takes a single numeric parameter and returns"
2030 LPRINT "its square"
2040 RETURN
Personal tools
Namespaces

Variants
Actions
Community
Explore
Misc
Toolbox