cairo-lang-doc 2.18.0

//! > Documentation

//! > test_runner_name
documentation_test_runner

//! > cairo_project.toml
[crate_roots]
hello = "src"

//! > cairo_code
//! This comment refers to the crate.

/// Main function comment outside.
/// Below there is a [`TraitTest`]
fn main() {
    //! Main function comment inside.
    println!("main");
}

/// Trait containing abc function. Below a [`main`] function
trait TraitTest {
    /// abc function returning u32.
    /// Default implementation of abc TraitTest function.
    fn abc() -> u32 {
        //! Default impl of abc TraitTest function inner comment.
        println!("default impl");
        32
    }
}

/// Implementation of TraitTest's abc function. Implements [this](TraitTest) trait.
impl TraitTestImpl of TraitTest {
    /// Default impl of abc TraitTest function.
    fn abc() -> u32 {
        //! Default impl of abc TraitTest function inner comment.
        println!("abc");
        32
    }
}

/// Test module used to check if the documentation is being attached to the nodes correctly. Inside
/// there is [this](test_module::inner_test_module_function) function.
pub mod test_module {
    //! Test module used to check if the documentation is being attached to the nodes correctly.
    /// Just a function outside the test_module.
    /// Above that module there is a [trait](super::TraitTest).
    pub fn inner_test_module_function() -> () {
        //! Just a function inside the test_module.
        println!("inside inner test module inner function");
    }
}

/// Point struct representing a point in a 2D space.
/// Example usage:
/// ```
///   fn new_Point() {
///     Point {x: 12, y: 14}
///   }
/// ```
/// [Point::bang]
#[derive(Drop)]
#[derive(Copy)]
struct Point {
    /// X coordinate.
    pub x: u32,
    /// Y coordinate.
    y: u32,
}

/// Answer Enum representing an answer to a yes/no question.
/// It will just refer in the docs to some wrong [item_that_does_not_exist] and also to
/// [this](another_not_existing_path).
/// But [this](Answer::Yes) is an existing variant of Answer
enum Answer {
    /// Yes answer variant.
    Yes,
    /// No answer variant.
    No,
}

/// Example usage:
/// ```
///   fn new_circle() {
///     // [Circle] <- this should not tokenize as a link (neither be resolved), we're inside code
///     block.
///   }
/// ```
struct Circle {}

/// Below there is a code example
///
///     First line of code
///     // Comment inside the code block, that should be ignored. [Square] <- it will be ignored as
///     well.
///     Second line of code
///
struct Square {}


/// This glass is droppable.
#[derive(Drop)]
/// When it's dropped, it shatters.
struct Glass {}

/// This cup is droppable.
#[derive(Drop)]
/// When it's dropped, it shatters.
struct Cup {}

pub trait TryInto<T, S> {
    fn try_into(self: T) -> Option<S>;
}

//! > Item signature #1

//! > Item documentation #1
This comment refers to the crate.

//! > Item documentation tokens #1
Content("This comment refers to the crate.")

//! > Item signature #2
fn main()

//! > Item documentation #2
Main function comment outside.
Below there is a [`TraitTest`] Main function comment inside.

//! > Item documentation tokens #2
Content("Main function comment outside.")
Content("\n")
Content("Below there is a ")
CommentLinkToken { label: "`TraitTest`", path: None, md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(48)), end: TextOffset(TextWidth(61)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(50)), end: TextOffset(TextWidth(59)) }), dest_text: Some("TraitTest") } }
Content(" ")
Content("Main function comment inside.")

//! > Item signature #3
trait TraitTest

//! > Item documentation #3
Trait containing abc function. Below a [`main`] function

//! > Item documentation tokens #3
Content("Trait containing abc function. Below a ")
CommentLinkToken { label: "`main`", path: None, md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(39)), end: TextOffset(TextWidth(47)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(41)), end: TextOffset(TextWidth(45)) }), dest_text: Some("main") } }
Content(" function")

//! > Item signature #4
fn abc() -> u32

//! > Item documentation #4
abc function returning u32.
Default implementation of abc TraitTest function. Default impl of abc TraitTest function inner comment.

//! > Item documentation tokens #4
Content("abc function returning u32.")
Content("\n")
Content("Default implementation of abc TraitTest function.")
Content(" ")
Content("Default impl of abc TraitTest function inner comment.")

//! > Item signature #5
impl TraitTestImpl of TraitTest;

//! > Item documentation #5
Implementation of TraitTest's abc function. Implements [this](TraitTest) trait.

//! > Item documentation tokens #5
Content("Implementation of TraitTest's abc function. Implements ")
CommentLinkToken { label: "this", path: Some("TraitTest"), md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(55)), end: TextOffset(TextWidth(72)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(62)), end: TextOffset(TextWidth(71)) }), dest_text: Some("TraitTest") } }
Content(" trait.")

//! > Item signature #6
fn abc() -> u32

//! > Item documentation #6
Default impl of abc TraitTest function. Default impl of abc TraitTest function inner comment.

//! > Item documentation tokens #6
Content("Default impl of abc TraitTest function.")
Content(" ")
Content("Default impl of abc TraitTest function inner comment.")

//! > Item signature #7

//! > Item documentation #7
Test module used to check if the documentation is being attached to the nodes correctly. Inside
there is [this](test_module::inner_test_module_function) function. Test module used to check if the documentation is being attached to the nodes correctly.

//! > Item documentation tokens #7
Content("Test module used to check if the documentation is being attached to the nodes correctly. Inside")
Content("\n")
Content("there is ")
CommentLinkToken { label: "this", path: Some("test_module::inner_test_module_function"), md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(105)), end: TextOffset(TextWidth(152)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(112)), end: TextOffset(TextWidth(151)) }), dest_text: Some("test_module::inner_test_module_function") } }
Content(" function.")
Content(" ")
Content("Test module used to check if the documentation is being attached to the nodes correctly.")

//! > Item signature #8
pub fn inner_test_module_function()

//! > Item documentation #8
Just a function outside the test_module.
Above that module there is a [trait](super::TraitTest). Just a function inside the test_module.

//! > Item documentation tokens #8
Content("Just a function outside the test_module.")
Content("\n")
Content("Above that module there is a ")
CommentLinkToken { label: "trait", path: Some("super::TraitTest"), md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(70)), end: TextOffset(TextWidth(95)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(78)), end: TextOffset(TextWidth(94)) }), dest_text: Some("super::TraitTest") } }
Content(".")
Content(" ")
Content("Just a function inside the test_module.")

//! > Item signature #9
#[derive(Drop)]
#[derive(Copy)]
struct Point {
    pub x: u32,
    y: u32,
}

//! > Item documentation #9
Point struct representing a point in a 2D space.
Example usage:
```cairo
  fn new_Point() {
    Point {x: 12, y: 14}
  }
```

[Point::bang]

//! > Item documentation tokens #9
Content("Point struct representing a point in a 2D space.")
Content("\n")
Content("Example usage:")
Content("\n")
Content("```cairo\n")
Content("  fn new_Point() {\n    Point {x: 12, y: 14}\n  }\n")
Content("```\n")
Content("\n")
CommentLinkToken { label: "Point::bang", path: None, md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(120)), end: TextOffset(TextWidth(133)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(121)), end: TextOffset(TextWidth(132)) }), dest_text: Some("Point::bang") } }

//! > Item signature #10
pub x: u32

//! > Item documentation #10
X coordinate.

//! > Item documentation tokens #10
Content("X coordinate.")

//! > Item signature #11
y: u32

//! > Item documentation #11
Y coordinate.

//! > Item documentation tokens #11
Content("Y coordinate.")

//! > Item signature #12
enum Answer {
    Yes,
    No,
}

//! > Item documentation #12
Answer Enum representing an answer to a yes/no question.
It will just refer in the docs to some wrong [item_that_does_not_exist] and also to
[this](another_not_existing_path).
But [this](Answer::Yes) is an existing variant of Answer

//! > Item documentation tokens #12
Content("Answer Enum representing an answer to a yes/no question.")
Content("\n")
Content("It will just refer in the docs to some wrong ")
CommentLinkToken { label: "item_that_does_not_exist", path: None, md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(102)), end: TextOffset(TextWidth(128)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(103)), end: TextOffset(TextWidth(127)) }), dest_text: Some("item_that_does_not_exist") } }
Content(" and also to")
Content("\n")
CommentLinkToken { label: "this", path: Some("another_not_existing_path"), md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(141)), end: TextOffset(TextWidth(174)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(148)), end: TextOffset(TextWidth(173)) }), dest_text: Some("another_not_existing_path") } }
Content(".")
Content("\n")
Content("But ")
CommentLinkToken { label: "this", path: Some("Answer::Yes"), md_link: MarkdownLink { link_span: TextSpan { start: TextOffset(TextWidth(180)), end: TextOffset(TextWidth(199)) }, dest_span: Some(TextSpan { start: TextOffset(TextWidth(187)), end: TextOffset(TextWidth(198)) }), dest_text: Some("Answer::Yes") } }
Content(" is an existing variant of Answer")

//! > Item signature #13
Yes

//! > Item documentation #13
Yes answer variant.

//! > Item documentation tokens #13
Content("Yes answer variant.")

//! > Item signature #14
No

//! > Item documentation #14
No answer variant.

//! > Item documentation tokens #14
Content("No answer variant.")

//! > Item signature #15
struct Circle {}

//! > Item documentation #15
Example usage:
```cairo
  fn new_circle() {
    // [Circle] <- this should not tokenize as a link (neither be resolved), we're inside code
    block.
  }
```

//! > Item documentation tokens #15
Content("Example usage:")
Content("\n")
Content("```cairo\n")
Content("  fn new_circle() {\n    // [Circle] <- this should not tokenize as a link (neither be resolved), we're inside code\n    block.\n  }\n")
Content("```")

//! > Item signature #16
struct Square {}

//! > Item documentation #16
Below there is a code example

    First line of code
    // Comment inside the code block, that should be ignored. [Square] <- it will be ignored as
    well.
    Second line of code

//! > Item documentation tokens #16
Content("Below there is a code example")
Content("\n")
Content("\n")
Content("    First line of code\n")
Content("    // Comment inside the code block, that should be ignored. [Square] <- it will be ignored as\n")
Content("    well.\n")
Content("    Second line of code")

//! > Item signature #17
#[derive(Drop)]
struct Glass {}

//! > Item documentation #17
This glass is droppable.
When it's dropped, it shatters.

//! > Item documentation tokens #17
Content("This glass is droppable.")
Content("\n")
Content("When it's dropped, it shatters.")

//! > Item signature #18
#[derive(Drop)]
struct Cup {}

//! > Item documentation #18
This cup is droppable.
When it's dropped, it shatters.

//! > Item documentation tokens #18
Content("This cup is droppable.")
Content("\n")
Content("When it's dropped, it shatters.")

//! > Item signature #19
pub trait TryInto<T, S>

//! > Item documentation #19

//! > Item documentation tokens #19

//! > Item signature #20
fn try_into(self: T) -> Option<S>

//! > Item documentation #20

//! > Item documentation tokens #20