From 075145be83479a420b617394083fb826933eb9e4 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Fri, 4 Jun 2021 19:16:10 +0530 Subject: [PATCH 1/5] Add documentation for the Cadence documentation generator --- tools/docgen/README.md | 72 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 tools/docgen/README.md diff --git a/tools/docgen/README.md b/tools/docgen/README.md new file mode 100644 index 0000000000..7b8d4e9fd9 --- /dev/null +++ b/tools/docgen/README.md @@ -0,0 +1,72 @@ +# Cadence Documentation Generator + +This is a tool to generate human-readable documentation for Cadence programs. +The tool currently supports generating documentation for following declarations: +- Composite types (Contracts, Structs, Resources, Enums) +- Interfaces (Contract interfaces, Struct interfaces, Resource Interfaces) +- Functions and Parameters +- Event declarations + + +The tool currently supports generating documentation in Markdown format. + +## How To Run +`go run /tools/docgen/main.go ` + +## Documentation Comments Format +Documentation comments (aka "docstrings": line comments starts with `///`, or block comments starting with `/**`) +added in a Cadence code are processed by the tool. +[Standard Markdown format](https://www.markdownguide.org/basic-syntax/) is supported in documentation comments, +with a bit of Cadence flavour. +Any Markdown syntax used within the comments would be honoured and rendered like a standard Markdown snippet. +This gives the flexibility for the developers to write well-structured documentations. +
+e.g: A set of bullet points added using Markdown bullets syntax, would be rendered as bullet points in the +generated documentation as well. + +### Function Documentation +Function documentation may start with a description of the function. +It also supports a special set of tags to document parameters and return types. +Parameters can be documented using the `@param` tag, followed by the parameter name, a colon (`:`) and the parameter description. +The return type can be documented using the `@return` tag. + +``` +/// This is the description of the function. This function adds two values. +/// +/// @param a: First integer value to add +/// @param b: Second integer value to add +/// @return Addition of the two arguments `a` and `b` +/// +pub fun add(a: Int, b: Int): Int { +} +``` + +## Best Practices +- Avoid using headings, horizontal-lines in the documentation. + - It could potentially conflict with the headers and lines added by the tool, when generating the documentation + - This may cause the generated documentation to be rendered in a disorganized manner. +- Use inline-codes (within backticks `` `foo` ``) when referring to names/identifiers in the code. + - e.g: Referring to a function name, parameter names, etc. + ``` + /// This is the description of the function. + /// This function adds `a` and `b` values. + /// + pub fun add(a: Int, b: Int): Int { + } + ``` +- When documenting function parameters and return type, avoid mixing parameter/return-type documentations + with the description of the function. e.g: + ``` + /// This is the description of the function. + /// + /// @param a: First integer value to add + /// @param b: Second integer value to add + /// + /// This function adds two values. However, this is not the proper way to document it. + /// This part of the description is not in the proper place. + /// + /// @return Addition of the two arguments `a` and `b` + /// + pub fun add(a: Int, b: Int): Int { + } + ``` From 9e25ace71f4d03b0929957f883f0604800cc02ad Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Sat, 12 Jun 2021 10:43:16 +0530 Subject: [PATCH 2/5] Add sample for using markdown in doc-comments --- tools/docgen/README.md | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/tools/docgen/README.md b/tools/docgen/README.md index 7b8d4e9fd9..453947daaf 100644 --- a/tools/docgen/README.md +++ b/tools/docgen/README.md @@ -1,7 +1,7 @@ # Cadence Documentation Generator -This is a tool to generate human-readable documentation for Cadence programs. -The tool currently supports generating documentation for following declarations: +A tool to generate human-readable documentation for Cadence programs. +Supports generating documentation for following declarations: - Composite types (Contracts, Structs, Resources, Enums) - Interfaces (Contract interfaces, Struct interfaces, Resource Interfaces) - Functions and Parameters @@ -14,16 +14,33 @@ The tool currently supports generating documentation in Markdown format. `go run /tools/docgen/main.go ` ## Documentation Comments Format -Documentation comments (aka "docstrings": line comments starts with `///`, or block comments starting with `/**`) -added in a Cadence code are processed by the tool. -[Standard Markdown format](https://www.markdownguide.org/basic-syntax/) is supported in documentation comments, -with a bit of Cadence flavour. -Any Markdown syntax used within the comments would be honoured and rendered like a standard Markdown snippet. -This gives the flexibility for the developers to write well-structured documentations. -
+The documentation comments (i.e: "doc-strings" / "doc-comments": line comments starts with `///`, +or block comments starting with `/**`) available in Cadence programs are processed by the tool, +to produce human-readable documentations. + +### Markdown Support +Standard Markdown format is supported in doc-comments, with a bit of Cadence flavour. +This means, any Markdown syntax used within the comments would be honoured and rendered like a standard Markdown snippet. +It gives the flexibility for the developers to write well-structured documentations. + e.g: A set of bullet points added using Markdown bullets syntax, would be rendered as bullet points in the generated documentation as well. +Documentation Comment: +``` +/// This is the description of the function. You can use markdown syntax here. +/// Can use **bold** or _italic_ texts, or even bullet-points: +/// - Here's the first point. +/// - Can also use code snippets (eg: `a + b`) + ``` +Output: + +>This is the description of the function. You can use markdown syntax here.
+>Can use **bold** or _italic_ texts, or even bullet-points: +> - Here's the first point. +> - Can also use code snippets (eg: `a + b`) + + ### Function Documentation Function documentation may start with a description of the function. It also supports a special set of tags to document parameters and return types. From fe63a31aafef3b8ef3c68c6e48370e472bf5ecad Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Sat, 12 Jun 2021 10:43:48 +0530 Subject: [PATCH 3/5] Add a section on documnetation comments to the cadence docs --- docs/language/syntax.md | 18 ++++++++++++++++++ tools/docgen/README.md | 5 ++++- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/language/syntax.md b/docs/language/syntax.md index 9e3c70e6f8..4aa2e05476 100644 --- a/docs/language/syntax.md +++ b/docs/language/syntax.md @@ -37,6 +37,24 @@ Multi-line comments are balanced. /* this is a // comment up to here */ this is not part of the comment */ ``` +### Documentation Comments +Documentation comments (also known as "doc-strings" ro "doc-comment") are a special set of comments that would be +processed by various tools to generate human-readable documentations for cadence programs. + +Single line doc-comments starts with three slashes (`///`) +```cadence +/// This is a documnetation comment on a single line. +/// Another documnetation comment line that is not executed. + +let x = 1 +``` + +Multi-line doc-comments comments start with a slash followed by two asterisks (`/**`) +```cadence +/** This is a documnetation comment + which spans multiple lines. **/ +``` + ## Names Names may start with any upper or lowercase letter (A-Z, a-z) diff --git a/tools/docgen/README.md b/tools/docgen/README.md index 453947daaf..fa8d2ed0f7 100644 --- a/tools/docgen/README.md +++ b/tools/docgen/README.md @@ -11,7 +11,10 @@ Supports generating documentation for following declarations: The tool currently supports generating documentation in Markdown format. ## How To Run -`go run /tools/docgen/main.go ` +Navigate to `/tools/docgen` directory and run: +``` +go run main.go +``` ## Documentation Comments Format The documentation comments (i.e: "doc-strings" / "doc-comments": line comments starts with `///`, From 6219be6003e7e6929d7f3621551f39d7aa810e65 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Mon, 14 Jun 2021 21:56:39 +0530 Subject: [PATCH 4/5] Fix documentation Co-authored-by: Joshua Hannan --- docs/language/syntax.md | 6 +++--- tools/docgen/README.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/language/syntax.md b/docs/language/syntax.md index 4aa2e05476..7b90cd80e9 100644 --- a/docs/language/syntax.md +++ b/docs/language/syntax.md @@ -38,10 +38,10 @@ Multi-line comments are balanced. ``` ### Documentation Comments -Documentation comments (also known as "doc-strings" ro "doc-comment") are a special set of comments that would be -processed by various tools to generate human-readable documentations for cadence programs. +Documentation comments (also known as "doc-strings" or "doc-comment") are a special set of comments that would be +processed by various tools to generate human-readable documentation for cadence programs. -Single line doc-comments starts with three slashes (`///`) +Single line doc-comments start with three slashes (`///`) ```cadence /// This is a documnetation comment on a single line. /// Another documnetation comment line that is not executed. diff --git a/tools/docgen/README.md b/tools/docgen/README.md index fa8d2ed0f7..56f7f3b8e7 100644 --- a/tools/docgen/README.md +++ b/tools/docgen/README.md @@ -26,7 +26,7 @@ Standard Markdown format is supported in doc-comments, with a bit of Cadence fla This means, any Markdown syntax used within the comments would be honoured and rendered like a standard Markdown snippet. It gives the flexibility for the developers to write well-structured documentations. -e.g: A set of bullet points added using Markdown bullets syntax, would be rendered as bullet points in the +e.g: A set of bullet points added using Markdown bullets syntax would be rendered as bullet points in the generated documentation as well. Documentation Comment: From 433b131619fdfe17a3f2ca4eb008ff56cda4a968 Mon Sep 17 00:00:00 2001 From: Supun Setunga Date: Tue, 15 Jun 2021 08:39:12 +0530 Subject: [PATCH 5/5] Improve the docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bastian Müller --- docs/language/syntax.md | 19 +++++++++++-------- tools/docgen/README.md | 20 ++++++++++---------- 2 files changed, 21 insertions(+), 18 deletions(-) diff --git a/docs/language/syntax.md b/docs/language/syntax.md index 7b90cd80e9..043cd80b46 100644 --- a/docs/language/syntax.md +++ b/docs/language/syntax.md @@ -38,21 +38,24 @@ Multi-line comments are balanced. ``` ### Documentation Comments -Documentation comments (also known as "doc-strings" or "doc-comment") are a special set of comments that would be -processed by various tools to generate human-readable documentation for cadence programs. +Documentation comments (also known as "doc-strings" or "doc-comment") are a special set of comments that can be +processed by tools, for example to generate human-readable documentation, or provide documentation in an IDE. + +Doc-comments either start with three slashes (`///`) on each line, +or are surrounded by `/**` and `**/`. -Single line doc-comments start with three slashes (`///`) ```cadence -/// This is a documnetation comment on a single line. -/// Another documnetation comment line that is not executed. +/// This is a documentation comment for `x`. +/// It spans multiple lines. let x = 1 ``` -Multi-line doc-comments comments start with a slash followed by two asterisks (`/**`) ```cadence -/** This is a documnetation comment - which spans multiple lines. **/ +/** + This is a documentation comment + which also spans multiple lines. +**/ ``` ## Names diff --git a/tools/docgen/README.md b/tools/docgen/README.md index 56f7f3b8e7..fb4a558261 100644 --- a/tools/docgen/README.md +++ b/tools/docgen/README.md @@ -17,7 +17,7 @@ go run main.go ``` ## Documentation Comments Format -The documentation comments (i.e: "doc-strings" / "doc-comments": line comments starts with `///`, +The documentation comments ("doc-strings" / "doc-comments": line comments starting with `///`, or block comments starting with `/**`) available in Cadence programs are processed by the tool, to produce human-readable documentations. @@ -65,15 +65,15 @@ pub fun add(a: Int, b: Int): Int { - Avoid using headings, horizontal-lines in the documentation. - It could potentially conflict with the headers and lines added by the tool, when generating the documentation - This may cause the generated documentation to be rendered in a disorganized manner. -- Use inline-codes (within backticks `` `foo` ``) when referring to names/identifiers in the code. - - e.g: Referring to a function name, parameter names, etc. - ``` - /// This is the description of the function. - /// This function adds `a` and `b` values. - /// - pub fun add(a: Int, b: Int): Int { - } - ``` +- Use inline-codes (within backticks `` `foo` ``) when referring to names/identifiers (such as function names, + parameter names, etc.) in the code. + ``` + /// This is the description of the function. + /// This function adds `a` and `b` values. + /// + pub fun add(a: Int, b: Int): Int { + } + ``` - When documenting function parameters and return type, avoid mixing parameter/return-type documentations with the description of the function. e.g: ```