CDE

Task/Documentation/0DESCRIPTION

@@ -0,0 +1 @@
+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.

Task/Documentation/1META.yaml

@@ -0,0 +1,2 @@
+---
+note: Software Engineering

Task/Documentation/Ada/documentation.ada

@@ -0,0 +1,25 @@
+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;

Task/Documentation/AutoHotkey/documentation.ahk

@@ -0,0 +1,17 @@
+;
+; 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
+}

Task/Documentation/C/documentation.c

@@ -0,0 +1,13 @@
+/**
+ * \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;
+}

Task/Documentation/Clojure/documentation.clj

@@ -0,0 +1,7 @@
+(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"
+  [])

Task/Documentation/D/documentation.d

@@ -0,0 +1,29 @@
+/**
+ * This is a documentation comment for somefunc and somefunc2.
+ * Does not need to be preceded by '*' in every line - this is done purely for code style
+ * $(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
+ * BUGS:
+ *     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)
+{
+}
+/++ Another documentation comment +/
+void main()
+{
+}

Task/Documentation/Delphi/documentation.delphi

@@ -0,0 +1,10 @@
+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;

Task/Documentation/E/documentation.e

@@ -0,0 +1,8 @@
+? /** This is an object with documentation */
+> def foo {
+>   # ...
+> }
+# value: <foo>
+
+? foo.__getAllegedType().getDocComment()
+# value: " This is an object with documentation "

Task/Documentation/Eiffel/documentation-1.e

@@ -0,0 +1,88 @@
+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

Task/Documentation/Eiffel/documentation-2.e

@@ -0,0 +1,63 @@
+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

Task/Documentation/Go/documentation.go

@@ -0,0 +1,25 @@
+// 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

Task/Documentation/Haskell/documentation-1.hs

@@ -0,0 +1,26 @@
+-- |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

Task/Documentation/Haskell/documentation-2.hs

@@ -0,0 +1,25 @@
+############################################################################
+#
+#	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

Task/Documentation/Haskell/documentation-3.hs

@@ -0,0 +1 @@
+XYZ

Task/Documentation/Java/documentation.java

@@ -0,0 +1,22 @@
+/**
+ * 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
+   }
+}

Task/Documentation/PicoLisp/documentation.l

@@ -0,0 +1,5 @@
+: (doc 'car)         # View documentation of a function
+
+: (doc '+Entity)     # View documentation of a class
+
+: (doc '+ 'firefox)  # Explicitly specify a browser

Task/Documentation/Python/documentation-1.py

@@ -0,0 +1,8 @@
+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

Task/Documentation/Python/documentation-2.py

@@ -0,0 +1,11 @@
+>>> 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
+
+>>>

Task/Documentation/R/documentation-1.r

@@ -0,0 +1 @@
+example(package.skeleton)

Task/Documentation/R/documentation-2.r

@@ -0,0 +1,59 @@
+\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

Task/Documentation/REXX/documentation.rexx

@@ -0,0 +1,36 @@
+/*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.   */

Task/Documentation/Racket/documentation.rkt

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

Task/Documentation/Ruby/documentation.rb

@@ -0,0 +1,35 @@
+=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

Task/Documentation/Smalltalk/documentation.st

@@ -0,0 +1 @@
+FooClass comment: 'This is a comment ....'.

Task/Documentation/Tcl/documentation.tcl

@@ -0,0 +1,18 @@
+#****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]
+}