From 3cf891f1128455a86868e85e765ce2a2598659af Mon Sep 17 00:00:00 2001 From: Mateusz Kowalski Date: Tue, 3 Dec 2024 10:53:16 +0100 Subject: [PATCH 1/3] Add linkage docs to scarb doc --- .../extensions/documentation-generation.md | 31 ++++++++++++++++--- 1 file changed, 27 insertions(+), 4 deletions(-) diff --git a/website/docs/extensions/documentation-generation.md b/website/docs/extensions/documentation-generation.md index bcc5ba61e..dc6ffe67d 100644 --- a/website/docs/extensions/documentation-generation.md +++ b/website/docs/extensions/documentation-generation.md @@ -9,7 +9,21 @@ ## Available types of comments -As for now, only the `///` comment prefix is supported. +As for now, we support those types of comments: + +- `///` documentation for following item. +- `//!` documentation for enclosing item (also works with file modules). + + +the `///` and `//!` comment prefixes are supported. + +## Item linkage + +You can also link to another item's page by just refering the item within the documentation comment. +Currenctly we support 2 types of links: + +- `[ItemName]` and ```[`ItemName`]``` (where `ItemName` is a valid path to an item). +- `[any label you want](ItemPath)`. ## mdBook @@ -25,7 +39,11 @@ Requirements: Let's take, for example, a simple Cairo project initalized using `scarb new`. Let's change the code inside `lib.cairo` to: ````cairo -/// Example Enum. +//! This module is an example one. +//! It tries to show how documentation comments work. + + +/// Example Enum. It's really similar to [ExampleStruct] enum ExampleEnum { /// First enum variant. VARIANT_A, @@ -33,12 +51,14 @@ enum ExampleEnum { VARIANT_B } -/// Example struct. Contains a public field and a private one. +/// Example struct. Contains a public field and a private one. struct ExampleStruct { /// Private field. field_a: felt252, /// Public field. - pub field_b: felt252 + pub field_b: felt252, + /// [`ExampleEnum`] field + field_c: ExampleEnum } /// Function that prints "test" to stdout with endline. @@ -53,8 +73,11 @@ fn test() { } /// Main function that Cairo runs as a binary entrypoint. +/// This function uses [that](test) function. fn main() { + //! This is an inner comment. It refers to it's parent which is the main function. println!("hello_world"); + test(); } ```` From 52975fcd99da3eb7f344f9bf3dc769e9831c71c4 Mon Sep 17 00:00:00 2001 From: Mateusz Kowalski Date: Tue, 3 Dec 2024 12:03:15 +0100 Subject: [PATCH 2/3] Get rid of []() from docs --- website/docs/extensions/documentation-generation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/docs/extensions/documentation-generation.md b/website/docs/extensions/documentation-generation.md index dc6ffe67d..de41a0e86 100644 --- a/website/docs/extensions/documentation-generation.md +++ b/website/docs/extensions/documentation-generation.md @@ -20,10 +20,9 @@ the `///` and `//!` comment prefixes are supported. ## Item linkage You can also link to another item's page by just refering the item within the documentation comment. -Currenctly we support 2 types of links: +Currenctly we support only those types of links: - `[ItemName]` and ```[`ItemName`]``` (where `ItemName` is a valid path to an item). -- `[any label you want](ItemPath)`. ## mdBook @@ -73,7 +72,7 @@ fn test() { } /// Main function that Cairo runs as a binary entrypoint. -/// This function uses [that](test) function. +/// This function uses [test] function. fn main() { //! This is an inner comment. It refers to it's parent which is the main function. println!("hello_world"); From e28110526d55b9c8adfb106e6c2744003001b49c Mon Sep 17 00:00:00 2001 From: Mateusz Kowalski Date: Tue, 3 Dec 2024 12:38:31 +0100 Subject: [PATCH 3/3] Fix prettier --- website/docs/extensions/documentation-generation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/website/docs/extensions/documentation-generation.md b/website/docs/extensions/documentation-generation.md index de41a0e86..e9c3c34ae 100644 --- a/website/docs/extensions/documentation-generation.md +++ b/website/docs/extensions/documentation-generation.md @@ -14,7 +14,6 @@ As for now, we support those types of comments: - `///` documentation for following item. - `//!` documentation for enclosing item (also works with file modules). - the `///` and `//!` comment prefixes are supported. ## Item linkage @@ -22,7 +21,7 @@ the `///` and `//!` comment prefixes are supported. You can also link to another item's page by just refering the item within the documentation comment. Currenctly we support only those types of links: -- `[ItemName]` and ```[`ItemName`]``` (where `ItemName` is a valid path to an item). +- `[ItemName]` and ``[`ItemName`]`` (where `ItemName` is a valid path to an item). ## mdBook @@ -50,7 +49,7 @@ enum ExampleEnum { VARIANT_B } -/// Example struct. Contains a public field and a private one. +/// Example struct. Contains a public field and a private one. struct ExampleStruct { /// Private field. field_a: felt252,