[2/2] lucy-clownfish git commit: Document DocuComments

[nw...@apache.org]

Document DocuComments


Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/a6112d69
Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/a6112d69
Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/a6112d69

Branch: refs/heads/master
Commit: a6112d69fb6d09098a4743aaf09e79ece93ef971
Parents: f651109
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Thu Feb 11 16:45:56 2016 +0100
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Thu Feb 11 16:45:56 2016 +0100

----------------------------------------------------------------------
 runtime/core/Clownfish/Docs/WritingClasses.md | 41 ++++++++++++++++++++++
 1 file changed, 41 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/a6112d69/runtime/core/Clownfish/Docs/WritingClasses.md
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Docs/WritingClasses.md b/runtime/core/Clownfish/Docs/WritingClasses.md
index 1967bfe..806c06f 100644
--- a/runtime/core/Clownfish/Docs/WritingClasses.md
+++ b/runtime/core/Clownfish/Docs/WritingClasses.md
@@ -526,3 +526,44 @@ Example:
         SUPER_DESTROY(self, PATH);
     }
 
+## Documentation
+
+The Clownfish compiler creates documentation in the host language's preferred
+format from so-called DocuComments found in the `.cfh` files. DocuComments use
+Markdown ([CommonMark](http://commonmark.org/) flavor) for formatting.
+DocuComments are multi-line C-style comments that start with `/**`. They
+immediately precede the documented class, inert function, or method.
+A left border consisting of whitespace and asterisks is stripped.
+
+The DocuComment for a class should start with a sentence (everything up until
+the first period `.`) in the format "class name - short description."
+
+DocuComments for functions and methods may end with a series of `@param` and
+`@return` directives which document the parameters and return values.
+
+Example:
+
+    /** Train - Class describing a train.
+     *
+     * The Train class describes a train.
+     */
+    public class Train inherits Vehicle {
+        /** Create a new Train object.
+         *
+         * @param max_speed The maximum speed in km/h.
+         * @param track_gauge The track gauge in mm.
+         */
+        public inert incremented Train*
+        new(double max_speed, double track_gauge);
+
+        /** Accessor for maximum speed.
+         *
+         * @return the maximum speed in km/h.
+         */
+        public double
+        Get_Max_Speed(Train *self);
+    }
+
+The Clownfish compiler also looks for standalone Markdown `.md` files in the
+source directories which will be included in the documentation.
+