Fix documentation of 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/fd74182c Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/fd74182c Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/fd74182c Branch: refs/heads/master Commit: fd74182c1f067392da659511dfdef0f587432bba Parents: 72f27b7 Author: Nick Wellnhofer <[email protected]> Authored: Fri Feb 26 12:43:48 2016 +0100 Committer: Nick Wellnhofer <[email protected]> Committed: Fri Feb 26 12:43:48 2016 +0100 ---------------------------------------------------------------------- runtime/core/Clownfish/Docs/WritingClasses.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/fd74182c/runtime/core/Clownfish/Docs/WritingClasses.md ---------------------------------------------------------------------- diff --git a/runtime/core/Clownfish/Docs/WritingClasses.md b/runtime/core/Clownfish/Docs/WritingClasses.md index bbd4f6d..350a42d 100644 --- a/runtime/core/Clownfish/Docs/WritingClasses.md +++ b/runtime/core/Clownfish/Docs/WritingClasses.md @@ -535,17 +535,19 @@ 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." +The DocuComment for a class should start with a short description (everything +up until the first period `.`) which may appear in the name section of a +man page, for example. 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. + /** Class describing a train. * - * The Train class describes a train. + * The Train class describes a train. It extends the Vehicle class and + * adds some useful properties specific to trains. */ public class Train inherits Vehicle { /** Create a new Train object.
