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 <[email protected]> Authored: Thu Feb 11 16:45:56 2016 +0100 Committer: Nick Wellnhofer <[email protected]> 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. +
