Documentation

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.

Haskell

Haddock is a popular documentation generator for the Haskell language.

<lang haskell>-- |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</lang>

See this chapter for more information about the markup.

J

Use scripdoc: <lang j>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=: }.</lang>

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 @. <lang java>/**

* 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
  }

}</lang>

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

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.

<lang python>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</lang>

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

>>> </lang>

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.

Translating Java's example: <lang ruby>=begin rdoc RDoc is documented here[1].

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

1. :include:boilerplate.txt</lang>

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: <lang tcl>#****f* RosettaCode/TclDocDemo

1. FUNCTION
2. TclDocDemo is a simple illustration of how to do documentation
3. of Tcl code using Robodoc.
4. SYNOPSYS
5. TclDocDemo foo bar
6. INPUTS
7. foo -- the first part of the message to print
8. bar -- the last part of the message to print
9. RESULT
10. No result
11. NOTES
12. Prints a message based on a template by filling in with the
13. supplied strings.

proc TclDocDemo {foo bar} {

   puts [format "%s -- %s" $foo $bar]

}</lang> Both doctools and robodoc can produce output in multiple formats.