Anonymous user
Documentation: Difference between revisions
BLC docs
m (Add accidentally omitted word) |
imported>Tromp (BLC docs) |
||
| (21 intermediate revisions by 14 users not shown) | |||
Line 6:
* Related task: [[Here_document]]
<br><br>
=={{header|6502 Assembly}}==
The language doesn't support this on its own, you'll have to do it with comments.
=={{header|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.
Line 15 ⟶ 16:
Example ADS file for instrumenting sorting functions:
<
generic
Line 39 ⟶ 40:
procedure Put (File : in out File_Type);
end Instrument;</
There is also a tool called [http://sourceforge.net/projects/adadoc/ 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.
=={{header|Arturo}}==
<syntaxhighlight lang="rebol">f: function [x :integer, y :integer][
;; description: « takes two integers and adds them up
;; options: [
;; double: « also multiply by two
;; ]
;; returns: :integer
result: x+y
if not? null? attr 'double -> result: result * 2
return result
]
info'f</syntaxhighlight>
{{out}}
<pre>|--------------------------------------------------------------------------------
| f :function 0x10AAE6600
|--------------------------------------------------------------------------------
| takes two integers and adds them up
|--------------------------------------------------------------------------------
| usage f x :integer
| y :integer
|
| options .double -> also multiply by two
|
| returns :integer
|--------------------------------------------------------------------------------</pre>
=={{header|AutoHotkey}}==
You can use the [http://www.autohotkey.com/forum/viewtopic.php?t=22548 GenDocs library].<br>
It generates html documentation in the style of the canonical ahk [http://www.autohotkey.com/docs/commands/MsgBox.htm documentation]. <br>
[http://en.wikipedia.org/wiki/BBCode BBCode] is supported for markup. <br>
Example from the library distribution:<
; Function: example_add
; Description:
Line 61 ⟶ 94:
example_add(number1, number2, number3=0){
return number1 + number2 + number3
}</
=={{header|Binary Lambda Calculus}}==
One of the best ways to document BLC programs is to generate them from a lambda file using the blc tool from https://github.com/tromp/AIT
Lambda files support arbitrary identifiers, a let ... in construct, recursive definitions, and of course (Haskell style) comments.
Many of the BLC solutions on Rosetta Code link to the lambda file from which they were generated.
=={{header|C}}==
A common tool for generating documentation is [http://www.stack.nl/~dimitri/doxygen/ Doxygen]:
<
* \brief Perform addition on \p a and \p b.
*
Line 78 ⟶ 116:
return a + b;
}
</syntaxhighlight>
=={{header|C sharp|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 [http://aspalliance.com/696 this tutorial]. A list of available xml elements for use in documentation [http://aspalliance.com/696_Code_Documentation_in_NET.2 is here].
<syntaxhighlight lang="csharp">/// <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;
}
}</syntaxhighlight>
=={{header|Clojure}}==
<
#^{:doc "Metadata can contain documentation and can be added to vars like this."}
test1)
Line 87 ⟶ 149:
(defn test2
"defn and some other macros allow you add documentation like this. Works the same way"
[])</
=={{header|COBOL}}==
Line 104 ⟶ 166:
the HTML generation process.
<syntaxhighlight lang="cobol">
*>****L* cobweb/cobweb-gtk [0.2]
*> Author:
Line 162 ⟶ 224:
end program cobweb-gtk.
*>****
</
{{works with|GnuCOBOL}}
Line 171 ⟶ 233:
markup processors, like Sphinx ReStructureText or Markdown.
<syntaxhighlight lang="cobol">
>>IF docpass NOT DEFINED
Line 188 ⟶ 250:
ReStructuredText or other markup source ...
>>END-IF
</syntaxhighlight>
Extraction of documentation segments is feasible using just the Compiler
Line 227 ⟶ 289:
"the person class"
=={{header|
The Crystal compiler comes with the <code>crystal docs</code> tool, which generates documentation from markdown embedded in source comments. The language's [https://crystal-lang.org/reference/conventions/documenting_code.html reference] goes into detail about the intricacies of the tool
<syntaxhighlight lang="ruby"># Any block of comments *directly* before (no blank lines) a module, class, or method is used as a doc comment
# This one is for a module
module Documentation
# This comment documents a class, *and* it uses markdown
class Foo
# This comment doesn't do anything, because it isn't directly above a module, class, or method
# Finally, this comment documents a method
def initialize
end
end
end</syntaxhighlight>
=={{header|D}}==
D compiler comes with a builtin documentation system called [http://digitalmars.com/d/1.0/ddoc.html Ddoc]. Alternative systems may be used (a common alternative is [http://www.stack.nl/~dimitri/doxygen/ Doxygen] which includes some D support).
<
This is a documentation comment for someFunc and someFunc2.
$(DDOC_COMMENT comment inside a documentation comment
Line 294 ⟶ 349:
/++ Another documentation comment +/
void main() {}</
=={{header|Delphi}}==
XML comments are shown in the IDE and is included in the XML documentation produced by the compiler when using --docs.
<syntaxhighlight lang="delphi">type
/// <summary>Sample class.</summary>
TMyClass = class
Line 308 ⟶ 363:
/// <exception cref="EConvertError">aValue is not a valid integer.</exception>
function StringToNumber(aValue: string): Integer;
end;</
=={{header|E}}==
Line 318 ⟶ 373:
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.
<
> def foo {
> # ...
Line 325 ⟶ 380:
? 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.
Line 335 ⟶ 390:
The following is a simple class written in Eiffel:
<
description: "Objects that model Times of Day: 00:00:00 - 23:59:59"
author: "Eiffel Software Construction Students"
Line 422 ⟶ 477:
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.
<
description: "Objects that model Times of Day: 00:00:00 - 23:59:59"
author: "Eiffel Software Construction Students"
Line 488 ⟶ 543:
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.
=={{header|Elixir}}==
Elixir uses [https://github.com/elixir-lang/ex_doc ExDoc] in order to document code. ExDoc allows users to pull data (such as name, version, source link) into their app. For example (taken from the ExDoc documentation):
<syntaxhighlight lang="elixir">
def project do
[app: :repo
Line 506 ⟶ 560:
deps: deps]
end
</syntaxhighlight>
Individual modules can be documented using the @moduledoc attribute and heredocs (with markdown):
<syntaxhighlight lang="elixir">
defmodule MyModule do
@moduledoc """
Line 520 ⟶ 574:
"""
end
</syntaxhighlight>
=={{header|Emacs Lisp}}==
In <code>defun</code>, <code>defmacro</code> and <code>defsubst</code> an optional docstring can follow the formal parameters.
<
"Say hello to the user."
(message "hello %d" n))</
For <code>defvar</code>, <code>defconst</code> or <code>defcustom</code> an optional docstring follows the value.
<
"The number one hundred.")</
Most other defining forms have similar optional docstrings. In all cases they must be a string constant.
Line 549 ⟶ 603:
=={{header|Fancy}}==
<
"""
This is a docstring. Every object in Fancy can have it's own docstring.
Line 561 ⟶ 615:
}
Foo docstring println # prints docstring Foo class
Foo instance_method: 'a_method . docstring println # prints method's docstring</
=={{header|Forth}}==
Common comments in the source code is lines starting by "\ " do not forget the space
example :
<syntaxhighlight lang="text">\ this is a comment</syntaxhighlight>
Another good practice is describing the stack use of a function : function ( stack before -- stack at end )
example :
<syntaxhighlight lang="text">: cubed ( n -- n^3 ) dup dup * * ; </syntaxhighlight>
=={{header|Fortran}}==
Line 584 ⟶ 651:
Outside systems are available to assist. It is common for text editors to employ syntax highlighting, but their designers rarely handle the full complexity of Fortran syntax correctly. For instance, the format of a number such as -3.145E+07 is difficult to scan, especially since in Fortran source, spaces are ignored outside of text literals. Then, consider the FORMAT codes, such as <code>31E16.7</code> and similar sequences. More serious efforts scan the Fortran source in order to extract information useful for documentation. There have long been available systems that will identify every routine in a programme and for each identify what routine calls it, and what routines it calls, along with further analysis on their parameters and their usage - this well before F90 introduced the optional INTENT feature. Similarly, within each routine, identify which variables are used (possibly as parameters) where and whether they are read or written there. And, analyse the usage of COMMON variables... Likewise, documentation might include a flowchart, and systems exist to produce these as well.
Aside from the Fortran source code alone, there are systems that will also inspect the commentary associated with the code, and, if their conventions are followed (quite reasonable conventions, quoth the designer: declare ''and describe'' each parameter straight away, ''etc. etc.''), will produce for example a .html file with all manner of crosslinkages. For instance, given <
REAL*8 A !Distance to the next node.
INTEGER N !Number of the current node.</
Quite useful documentation could be extracted just from that. By mixing actual source statements with the commentary and extracting ''both'', inane clashes can be reduced, as in <code>CHARACTER*6 TLA !Three-character name.</code> that arose because a modification to the nature of the parameter had been made, but, while revising every routine that employed such a parameter, the programmer's consciousness faded out as soon as it saw the comment start and noted "non-Fortran source", to the puzzlement of subsequent readers. A system that extracted only the commentary part from that would not give a correct report, whereas with it known that the actual declaration would be included, there would be no longer any need to repeat its details in the comment and the comment could confine itself to expounding on meaning and usage. On the other hand, F90 introduced a verbose scheme for declarations wherein something like <code>SELECTED_REAL_KIND(6, 70)</code> might appear and copying that may well merely copy obfuscation.
Line 592 ⟶ 659:
But none of this is within the Fortran language definition itself.
=={{header|FreeBASIC}}==
Line 617 ⟶ 671:
Example code demonstrating what godoc extracts and what it doesn't:
<
//
// A package comment preceeds the package clause and explains the purpose
Line 641 ⟶ 695:
// Doc not extracted.
var MEMEME int</
Text output of godoc: (HTML looks nicer, of course)
<pre>
Line 677 ⟶ 731:
New commands can have optional help text between the command name line and the opening <code>{</code> brace.
<
Print a greeting to the user.
This is only a short greeting.
{
show "hello"
}</
Any literal braces in the text must be backslash escaped <code>\{</code>. The text is shown by the online help system, similar to builtin commands.
<syntaxhighlight lang
(See section "Simple New Command" in the GRI manual.)
=={{header|Haskell}}==
[http://haskell.org/haddock/ Haddock] is a popular documentation generator for the Haskell language.
<
square1 :: Int -> Int
square1 x = x * x
Line 719 ⟶ 772:
-- |This is a documentation comment for the following type class
class Foo a where
bar :: a</
See [http://haskell.org/haddock/doc/html/markup.html this chapter] for more information about the markup.
Line 726 ⟶ 779:
==={{header|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
Line 751 ⟶ 804:
procedure x1() #: short description of procedure
</syntaxhighlight>
{{libheader|Icon Programming Library}}
* [http://www.cs.arizona.edu/icon/library/src/progs/ipldoc.icn ipldoc.icn] Program to collect library documentation.<br/>
* [http://www.cs.arizona.edu/icon/library/src/progs/iplindex.icn iplindex.icn] Program to produce indexed listing of the program library.
=={{header|Isabelle}}==
<syntaxhighlight lang="isabelle">theory Text
imports Main
begin
chapter ‹Presenting Theories›
text ‹This text will appear in the proof document.›
section ‹Some Examples.›
― ‹A marginal comment. The expression \<^term>‹True› holds.›
lemma True_is_True: "True" ..
text ‹
The overall content of an Isabelle/Isar theory may alternate between formal
and informal text.
›
text_raw ‹Can also contain raw latex.›
text ‹This text will only compile if the fact @{thm True_is_True} holds.›
text ‹This text will only compile if the constant \<^const>‹True› is defined.›
end</syntaxhighlight>
==={{header|Unicon}}===
<syntaxhighlight lang
{{improve|Unicon|Needs corresponding Unilib formats}}
Line 767 ⟶ 848:
=={{header|J}}==
Use [http://www.jsoftware.com/trac/base/browser/trunk/main/script/doc.ijs?rev=1 scripdoc]:
<
NB.*apply v apply verb x to y
apply=: 128!:2
Line 791 ⟶ 872:
usleep
3 : '''libc.so.6 usleep > i i''&(15!:0) >.y'
</syntaxhighlight>
=={{header|Java}}==
Documentation is typically given using [http://www.j2ee.me/j2se/javadoc/index.jsp 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 <code>/**</code>, end with <code>*/</code>, and usually have "tags" embedded starting with <code>@</code>.
<
* This is a class documentation comment. This text shows at the top of the page for this class
* @author Joe Schmoe
Line 816 ⟶ 897:
//...code here
}
}</
=={{header|Julia}}==
Line 825 ⟶ 906:
Any string appearing at the top-level right before an object (function, macro, type or instance) will be interpreted as documenting it (these are called docstrings). Note that no blank lines or comments may intervene between a docstring and the documented object. Here is a basic example:
<
"Tell whether there are too foo items in the array."
foo(xs::Array) = ...
</syntaxhighlight>
Documentation is interpreted as Markdown, so you can use indentation and code fences to delimit code examples from text. Technically, any object can be associated with any other as metadata; Markdown happens to be the default, but one can construct other string macros and pass them to the @doc macro just as well.
Line 834 ⟶ 915:
Here is a more complex example, still using Markdown:
<
"""
bar(x[, y])
Line 850 ⟶ 931:
"""
function bar(x, y) ...
</
=={{header|Kotlin}}==
Line 860 ⟶ 941:
The following is a slightly extended version of the example in the official Kotlin documentation:
<
* A group of *members*.
* @author A Programmer.
Line 878 ⟶ 959:
*/
fun add(member: T): Int { ... }
}</
=={{header|Lambdatalk}}==
Lambdatalk works in a small wiki, lambdatank, where can be written easily (as in a standard text editor) any informations about the keywords, the set of primitives, and the eventual user defined functions and libraries. For instance this is how a function is built, displayed and tested in the browser's window:
<syntaxhighlight lang="scheme">
'{def add // define the name
{lambda {:a :b} // for a function with two arguments
{+ :a :b} // whose body calls the + primitive on them
} // end function
} // end define
-> add
'{add 3 4} // call the function on two values
-> 7 // the result
</syntaxhighlight>
=={{header|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)).
Line 909 ⟶ 1,005:
:- end_object.
</syntaxhighlight>
=={{header|Lua}}==
Requires an external tool, the most widely-used of which (at present) is [https://github.com/lunarmodules/LDoc LDoc].
<syntaxhighlight lang="lua">--- Converts degrees to radians (summary).
-- Given an angle measure in degrees, return an equivalent angle measure in radians (long description).
-- @param deg the angle measure in degrees
-- @return the angle measure in radians
-- @see rad2deg
function deg2rad(deg) return deg*math.pi/180 end</syntaxhighlight>
=={{header|Mathematica}} / {{header|Wolfram Language}}==
Mathematica inline documentation can be accessed directly in the code by pressing F1. No external tools required
<
f::usage = "f[x,y] gives the sum of x and y"
?f
-> f[x,y] gives the sum of x and y</
=={{header|MATLAB}} / {{header|Octave}}==
Script files can contain comments (being whatever follows a % character) and for a script in file Gnash.m that is in the current execute path (so that typing "Gnash" will initiate it), the command "help Gnash" will instead display the first comment block at the start of the file. So, if it starts <
% My first MatLab attempt, to swallow data as produced by Gnash's DUMP
%command in a comma-separated format. Such files start with a line</
The comments will be revealed. However, a test with Octave elicited only the comment on the "function" line. If the file contained merely a sequence of commands (i.e. did not constitute the definition of a function) the first line of the above example would be absent and the file would start with a comment block.
=={{header|Neko}}==
'''nekoc -doc <file>''' generates XHTML documentation from within source. The compiler scans for <syntaxhighlight lang
Special <
The feature does not care what file type is used for input, and most C sources for Neko libraries include documentation blocks of this type.
<
result_set_conv_date : 'result -> function:1 -> void
<doc>Set the function that will convert a Date or DateTime string
to the corresponding value.</doc>
**/</
=={{header|Nim}}==
<
## hashes (##). To create the documentation run ``nim doc file.nim``.
## ``nim doc2 file.nim`` is the same, but run after semantic checking, which
Line 969 ⟶ 1,074:
## A useful procedure
for i in 1..times:
echo "hello world"</
=={{header|Objeck}}==
Documentation can be produced for bundles, classes and methods/functions.
<syntaxhighlight lang="objeck">#~
Sets the named row value
@param name name
@param value value
@return true of value was set, false otherwise
~#
method : public : Set(name : String, value : String) ~ Bool {
return Set(@table->GetRowId(name), value);
}
</syntaxhighlight>
=={{header|Objective-C}}==
Line 975 ⟶ 1,094:
===HeaderDoc===
<
@function add
@abstract Adds two numbers
Line 985 ⟶ 1,104:
int add(int a, int b) {
return a + b;
}</
=={{header|OCaml}}==
[http://caml.inria.fr/pub/docs/manual-ocaml/manual029.html OCamldoc] is a documentation generator that is included with OCaml. Documentation comments all start with <code>(**</code> (but no more than two asterisks) and end with <code>*)</code>. Like Javadoc, "tags" can be embedded starting with <code>@</code>.
=={{header|Ol}}==
No builtin documentation is provided in Ol. Use comments in source code and any resonable external tool, for example handmade scripts.
i.e.
<syntaxhighlight lang="scheme">
; note: use this script to generate a markdown file
; sed -n 's/\s*;!\s*//gp'
(import (owl parse))
;! # Documentation
;! ## Functions
;! ### whitespace
;! Returns a #true if argument is a space, newline, return or tab character.
(define whitespace (byte-if (lambda (x) (has? '(#\tab #\newline #\space #\return) x))))
;! ### maybe-whitespaces
;! Returns any amount (including 0) of whitespaces. Used as whitespace characters skipper in parses.
(define maybe-whitespaces (greedy* whitespace))
</syntaxhighlight>
Sed script:
<pre>sed -n 's/\s*;!\s*//gp'
</pre>
{{Out}}
<pre>
# Documentation
## Functions
### whitespace
Returns a #true if argument is a space, newline, return or tab character.
### maybe-whitespaces
Returns any amount (including 0) of whitespaces. Used as whitespace characters skipper in parses.
</pre>
=={{header|PARI/GP}}==
The primary method for documenting GP functions is the <code>addhelp()</code> command:
<
PARI documentation is done as for [[#C|C]].
Line 1,012 ⟶ 1,154:
Perl's documentation mechanism is called [http://perldoc.perl.org/perlpod.html POD (Plain Old Documentation)]. Basically, any line that starts with an equal sign followed by a word (e.g. <tt>=head1</tt>) starts a documentation comment; and it lasts until a line that begins with <tt>=cut</tt>. Many formatting commands are recognized; for example, a line beginning with <tt>=item</tt> starts a section for an item, text wrapped in <tt>I< ... ></tt> is italicized, text wrapped in <tt>C< ... ></tt> is formatted as code, etc. See the [http://perldoc.perl.org/perlpod.html perlpod] and [http://perldoc.perl.org/perlpodspec.html perlpodspec] manuals for more details about the format.
=={{header|
When running Edita/Edix, pressing F1 when on a builtin opens up the expected page in phix.chm.
The latter is painstakingly hand-crafted, and I think all the better for it.<br>
When on an application-specific routine, F1 opens up a window showing the actual definition, titled either
"Locally defined in this source" or fullpath & "[n/m]" with an "Examine code" button to directly edit it.
The "[n/m]" collects all possible (m) routines, as kept on a database of globals maintained via a periodic
background scan, combined with a quick re-scan of the current file, and defaults (n) to the most likely
from the project tree of the last run/file being edited. Pressing F1 again cycles through them.<br>
Ideally any routine-specific comments should be placed within the routine itself, eg (from pmain.e):
<!--<syntaxhighlight lang="phix">(phixonline)-->
<span style="color: #008080;">procedure</span> <span style="color: #000000;">StoreVar</span><span style="color: #0000FF;">(</span><span style="color: #004080;">integer</span> <span style="color: #000000;">N</span><span style="color: #0000FF;">,</span> <span style="color: #004080;">integer</span> <span style="color: #000000;">NTyp</span><span style="color: #0000FF;">)</span>
<span style="color: #000080;font-style:italic;">--
-- Store a variable, applying any final operator as needed.
-- If N is zero, PopFactor (ie store in a new temporary variable of
-- the specified type). Otherwise N should be an index to symtab.
-- If storeConst is 1, NTyp is ignored/overridden, otherwise it
-- should usually be the declared or local type of N.
-- </span>
<span style="color: #0000FF;">...</span>
<span style="color: #008080;">end</span> <span style="color: #008080;">procedure</span>
<!--</syntaxhighlight>-->
Note: As I understand it, tools such as Doxygen usually expect their markup to precede the actual definitions.
Obviously the above is targetted at programmers, rather than paying application-specific end-users.
=={{header|PHP}}==
Line 1,034 ⟶ 1,184:
=={{header|PicoLisp}}==
PicoLisp doesn't yet support inline documentation directly in the code. However, it has built-in runtime documentation via the '[http://software-lab.de/doc/refD.html#doc doc]' function. This requires no external tools, except that the interpreter must have been started in debug mode.
<
: (doc '+Entity) # View documentation of a class
: (doc '+ 'firefox) # Explicitly specify a browser</
=={{header|PL/I}}==
Line 1,047 ⟶ 1,197:
=={{header|PowerShell}}==
PowerShell includes complete built-in help for comment-based help: Just run help about_comment_based_help.
<syntaxhighlight lang="powershell">
help about_comment_based_help
</syntaxhighlight>
=={{header|PureBasic}}==
<
; documentation system.
Line 1,086 ⟶ 1,236:
CloseFile(file)
EndIf
EndProcedure</
This would as an example be shown in the code over view as the picture below.
Line 1,094 ⟶ 1,244:
A string literal which is the first expression in a class, function, or module definition is called a [http://docs.python.org/glossary.html#term-docstring docstring]. It can be subsequently accessed at runtime using the <code>.__doc__</code> attribute of the class, function, or module.
<
"""
This is a class docstring. Traditionally triple-quoted strings are used because
Line 1,101 ⟶ 1,251:
def method(self, num):
"""This is a method docstring."""
pass</
'''[http://docs.python.org/library/pydoc.html 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.
<
"takes no args and returns None after doing not a lot"
Line 1,116 ⟶ 1,266:
takes no args and returns None after doing not a lot
>>></
===Sphinx===
Line 1,123 ⟶ 1,273:
=={{header|R}}==
R objects are documented in files written in "R documentation" (Rd) format, which is similar to LaTeX markup. See Chapter 2 of [http://cran.r-project.org/doc/manuals/R-exts.pdf Writing R Extensions] for the full details. Example function document files can be created using
<syntaxhighlight lang
An example documentation file for a function 'f', taking arguments 'x' and 'y' is
<
\Rdversion{1.1}
\alias{f}
Line 1,183 ⟶ 1,333:
% R documentation directory.
\keyword{ ~kwd1 }
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line</
=={{header|Racket}}==
Line 1,190 ⟶ 1,340:
domain-specific language called Scribble:
<
#lang scribble/manual
(require (for-label "sandwiches.rkt"))
Line 1,198 ⟶ 1,348:
Returns a sandwich given the right ingredients.
}
</syntaxhighlight>
Programs can also be written with inline documentation using either the
<tt>scribble/srcdoc</tt> or <tt>scribble/lp</tt> (literate programming)
libraries.
=={{header|Raku}}==
(formerly Perl 6)
Similarly to Perl 5, Raku is documented using [https://docs.raku.org/language/pod 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.
<syntaxhighlight lang="raku" line>
#= 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"</syntaxhighlight>
A compiler has a built-in <code>--doc</code> switch that will generate documentation from a given source file. An output format can be specified in the switch. For example, <code>--doc=Markdown</code> will generate Markdown from Pod provided that the <code>Pod::To::Markdown</code> is installed.
=={{header|REBOL}}==
<
Title: "Documentation"
URL: http://rosettacode.org/wiki/Documentation
Line 1,268 ⟶ 1,437:
x: get in bob 'hi help x print ""
probe get in bob 'hi</
Output:
Line 1,316 ⟶ 1,485:
=={{header|Retro}}==
Retro uses a literate source format called Unu. Sources are typically using a subset of Markdown.
<syntaxhighlight lang="retro">
# Determine The Average Word Name Length
To determine the average length of a word name two values
are needed. First, the total length of all names in the
Dictionary:
~~~
#0 [ d:name s:length + ] d:for-each
~~~
And then the number of words in the Dictionary:
~~~
#0 [ drop n:inc ] d:for-each
~~~
With these, a simple division is all that's left.
~~~
/
~~~
Finally, display the results:
~~~
'Average_name_length:_%n\n s:format s:put
~~~
</syntaxhighlight>
This illustrates the format. Only code in the fenced blocks (between \[[User:Crc|Crc]] ([[User talk:Crc|talk]]) pairs) get extracted and run.
(Note: this only applies to *source files*; fences are not used when entering code interactively).
=={{header|REXX}}==
Line 1,348 ⟶ 1,533:
<br>Note that the documentation is bracketed by the standard REXX comment delimiters to preserve program lexicographical integrity.
<
parse arg doc /*obtain (all) the arguments from C.L. */
if doc='?' then call help /*show documentation if arg=a single ? */
Line 1,376 ⟶ 1,561:
If no "numberOfItems" are entered, the default of 100 is used.
</help>
════════════════════════════════════end of the in═line documentation BEFORE the </help> */</
===version 2===
<
* 13.10.2013 Walter Pachl another way to show documentation
* no tags and good enough if only one documentation block
Line 1,397 ⟶ 1,582:
say 'the program would be here!'
Exit
here: return sigl /* returns the invocation's line number */</
=={{header|Ring}}==
<
/*
Multiply two numbers
Line 1,410 ⟶ 1,595:
func mult n1, n2
return n1*n2
</syntaxhighlight>
=={{header|Ruby}}==
Line 1,420 ⟶ 1,605:
Ruby's documentation comments look like Perl's PODs. Translating Java's example:
<
RDoc is documented here[http://www.ruby-doc.org/core/classes/RDoc.html].
Line 1,454 ⟶ 1,639:
end
# :include:boilerplate.txt</
=={{header|Rust}}==
Line 1,474 ⟶ 1,659:
Here's an example of some heavily documented mock code:
<
//!
//! **Lorem ipsum** dolor sit amet, consectetur adipiscing elit. Aenean a
Line 1,530 ⟶ 1,715:
let foo = Whatchamabob{ doodad: 1.2, thingamabob: false };
foo.frob();
}</
=={{header|Scala}}==
Excellent documentation about ScalaDoc is given [https://docs.scala-lang.org/style/scaladoc.html here in the Scala Style Guide.]
<syntaxhighlight lang="scala">/**
* This is a class documentation comment. This text shows at the top of the page for this class
*
Line 1,555 ⟶ 1,740:
???
}
}</
=={{header|Smalltalk}}==
Most Smalltalk dialects have builtin tools to generate nice looking documentation (html pages) automatically, using its reflective features.
In addition, all support class comments as follows:
(Squeak/Pharo/VisualWorks/SmalltalkX)
<syntaxhighlight lang="smalltalk">FooClass comment: 'This is a comment ....'.</syntaxhighlight>
=={{header|SQL PL}}==
{{works with|Db2 LUW}}
{{libheader|db2doc}}
<
CREATE TABLESPACE myTs;
Line 1,685 ⟶ 1,873:
COMMENT ON ROLE mySeq IS 'Description of the sequence.';
</syntaxhighlight>
=={{header|Stata}}==
Line 1,692 ⟶ 1,880:
For instance, say we have an ado file '''hello.ado''':
<
di "Hello, World!"
end</
The documentation file, '''hello.sthlp''', could be:
Line 1,715 ⟶ 1,903:
=={{header|Swift}}==
Swift uses reStructuredText. [http://nshipster.com/swift-documentation/ This third-party article] has some information.
<
Adds two numbers
:param: a an integer.
Line 1,723 ⟶ 1,911:
func add(a: Int, b: Int) -> Int {
return a + b
}</
=={{header|Tcl}}==
Documentation for Tcl code is usually prepared in separate files using a tool like [http://wiki.tcl.tk/3054 doctools], but inline docs (with all their inherent limitations) can be done with the likes of [http://www.xs4all.nl/~rfsber/Robo/index.html Robodoc]. For example:
<
# FUNCTION
# TclDocDemo is a simple illustration of how to do documentation
Line 1,744 ⟶ 1,932:
proc TclDocDemo {foo bar} {
puts [format "%s -- %s" $foo $bar]
}</
Both doctools and robodoc can produce output in multiple formats.
{{omit from|M4}}
=={{header|Wren}}==
Wren source code has both single line (//) and block (/*..*/) comments. Block comments can also be nested.
However, there are currently no special tools for extracting documentation comments that I'm aware of.
<syntaxhighlight lang="wren">// The meaning of life!
var mol = 42
// A function to add two numbers
var add = Fn.new { |x, y| x + y }
/* A class with some string utilites */
class StrUtil {
// reverses an ASCII string
static reverse(s) { s[-1..0] }
// capitalizes the first letter of an ASCII string
static capitalize(s) {
var firstByte = s[0].bytes[0]
if (firstByte >= 97 && firstByte <= 122) {
firstByte = firstByte - 32
return String.fromByte(firstByte) + s[1..-1]
}
return s
}
}
// test code
var smol = "meaning of life"
System.print("'%(smol)' + 123 = %(add.call(mol, 123))")
System.print("'%(smol)' reversed = %(StrUtil.reverse(smol))")
System.print("'%(smol)' capitalized = %(StrUtil.capitalize(smol))")</syntaxhighlight>
{{out}}
<pre>
'meaning of life' + 123 = 165
'meaning of life' reversed = efil fo gninaem
'meaning of life' capitalized = Meaning of life
</pre>
=={{header|XPL0}}==
There are no external tools for inserting documentation into an XPL0
program other than by using a text editor to insert comments.
Comments can be inserted into code by enclosing them between backslashes.
Comments are always terminated by the end of the line.
Anything following double backslashes (\\) on a line is a comment (like
forward slashes in C).
Since single backslashes turn comments on and off, double backslashes are
useful for commenting out a line that may contain backslashes.
=={{header|ZX Spectrum Basic}}==
Line 1,753 ⟶ 1,993:
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:
<
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:
<
1999 STOP
2000 REM Print the documentation
Line 1,764 ⟶ 2,004:
2020 LPRINT "s is a function that takes a single numeric parameter and returns"
2030 LPRINT "its square"
2040 RETURN</
{{omit from|GUISS}}
| |||