You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucy.apache.org by nw...@apache.org on 2016/02/11 16:46:33 UTC
[1/2] lucy-clownfish git commit: Document exposure specifier
Repository: lucy-clownfish
Updated Branches:
refs/heads/master 0c5c166ee -> a6112d69f
Document exposure specifier
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/f6511096
Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/f6511096
Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/f6511096
Branch: refs/heads/master
Commit: f6511096034e44af0b0c26698c882183042771a5
Parents: 0c5c166
Author: Nick Wellnhofer <we...@aevum.de>
Authored: Thu Feb 11 16:24:21 2016 +0100
Committer: Nick Wellnhofer <we...@aevum.de>
Committed: Thu Feb 11 16:24:21 2016 +0100
----------------------------------------------------------------------
runtime/core/Clownfish/Docs/WritingClasses.md | 12 +++---------
1 file changed, 3 insertions(+), 9 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/f6511096/runtime/core/Clownfish/Docs/WritingClasses.md
----------------------------------------------------------------------
diff --git a/runtime/core/Clownfish/Docs/WritingClasses.md b/runtime/core/Clownfish/Docs/WritingClasses.md
index c7f5a49..1967bfe 100644
--- a/runtime/core/Clownfish/Docs/WritingClasses.md
+++ b/runtime/core/Clownfish/Docs/WritingClasses.md
@@ -132,7 +132,7 @@ This will generate:
### Class exposure
-TODO
+API documentation will only be generated for classes with public exposure.
### Inert classes
@@ -150,10 +150,8 @@ modifier. Final classes must not be inherited from.
Variables are declared with a declaration of the following form:
- variable-declaration = variable-exposure-specifier?
- variable-modifier*
+ variable-declaration = variable-modifier*
type variable-name ";"
- variable-exposure-specifier = "public"
variable-modifier = "inert"
variable-name = identifier
@@ -179,10 +177,6 @@ definition will look like:
int Path_max_path_length = 5000;
-### Inert variable exposure
-
-TODO
-
### Instance variables
Non-inert variables are instance variables and added to the class's ivars
@@ -246,7 +240,7 @@ Example using short names:
### Function exposure
-TODO
+API documentation will only be generated for functions with public exposure.
### Inert functions
[2/2] lucy-clownfish git commit: Document DocuComments
Posted by 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.
+