Skip to content

Commit 8d77118

Browse files
FroyaTheHenFroyaTheHen
authored
support italic and bold markdown syntax parsing documentation (#8072)
1 parent 3b9c086 commit 8d77118

File tree

8 files changed

+219
-19
lines changed

8 files changed

+219
-19
lines changed

‎crates/cairo-lang-doc/src/parser.rs‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,9 @@ impl<'db> DocumentationCommentParser<'db> {
175175
)));
176176
}
177177
Tag::List(list_type) => {
178-
tokens.push(DocumentationCommentToken::Content("\n".to_string()));
178+
if !list_nesting.is_empty() {
179+
tokens.push(DocumentationCommentToken::Content("\n".to_string()));
180+
}
179181
list_nesting.push(DocCommentListItem {
180182
delimiter: list_type,
181183
is_ordered_list: list_type.is_some(),
@@ -185,16 +187,16 @@ impl<'db> DocumentationCommentParser<'db> {
185187
CodeBlockKind::Fenced(language) => {
186188
if language.trim().is_empty() {
187189
tokens.push(DocumentationCommentToken::Content(String::from(
188-
"\n```cairo\n",
190+
"```cairo\n",
189191
)));
190192
} else {
191193
tokens.push(DocumentationCommentToken::Content(format!(
192-
"\n```{language}\n"
194+
"```{language}\n"
193195
)));
194196
}
195197
}
196198
CodeBlockKind::Indented => {
197-
tokens.push(DocumentationCommentToken::Content("\n\n".to_string()));
199+
tokens.push(DocumentationCommentToken::Content("\n".to_string()));
198200
is_indented_code_block = true;
199201
}
200202
},
@@ -236,11 +238,17 @@ impl<'db> DocumentationCommentParser<'db> {
236238
}
237239
Tag::Table(alignment) => {
238240
table_alignment = alignment;
239-
tokens.push(DocumentationCommentToken::Content("\n\n".to_string()));
241+
tokens.push(DocumentationCommentToken::Content("\n".to_string()));
240242
}
241243
Tag::TableCell => {
242244
tokens.push(DocumentationCommentToken::Content("|".to_string()));
243245
}
246+
Tag::Strong => {
247+
tokens.push(DocumentationCommentToken::Content("**".to_string()));
248+
}
249+
Tag::Emphasis => {
250+
tokens.push(DocumentationCommentToken::Content("_".to_string()));
251+
}
244252
_ => {}
245253
}
246254
}
@@ -285,13 +293,22 @@ impl<'db> DocumentationCommentParser<'db> {
285293
TagEnd::TableRow => {
286294
tokens.push(DocumentationCommentToken::Content("|".to_string()));
287295
}
296+
TagEnd::Strong => {
297+
tokens.push(DocumentationCommentToken::Content("**".to_string()));
298+
}
299+
TagEnd::Emphasis => {
300+
tokens.push(DocumentationCommentToken::Content("_".to_string()));
301+
}
302+
TagEnd::Paragraph => {
303+
tokens.push(DocumentationCommentToken::Content("\n".to_string()));
304+
}
288305
_ => {}
289306
},
290307
Event::SoftBreak => {
291308
tokens.push(DocumentationCommentToken::Content("\n".to_string()));
292309
}
293310
Event::Rule => {
294-
tokens.push(DocumentationCommentToken::Content("\n___\n".to_string()));
311+
tokens.push(DocumentationCommentToken::Content("___\n".to_string()));
295312
}
296313
_ => {}
297314
}

‎crates/cairo-lang-doc/src/tests/test-data/basic.txt‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,8 @@ Example usage:
231231
Content("Point struct representing a point in a 2d space.")
232232
Content("\n")
233233
Content("Example usage:")
234-
Content("\n```cairo\n")
234+
Content("\n")
235+
Content("```cairo\n")
235236
Content(" fn new_Point() {\n Point {x: 12, y: 14}\n }\n")
236237
Content("```\n")
237238
Content("\n")
@@ -313,7 +314,8 @@ Example usage:
313314

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

@@ -330,7 +332,8 @@ Below there is a code example
330332

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

‎crates/cairo-lang-doc/src/tests/test-data/comment_markers.txt‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,6 @@ fn map<U, F, +Destruct<F>, +core::ops::FnOnce<F, (T,)>[Output: U]>(
5454
Maps an `Option<T>` to `Option<U>` by applying a function to a contained value (if `Some`)
5555
or returns `None` (if `None`).
5656
# Examples
57-
5857
```cairo
5958
let maybe_some_string: Option<ByteArray> = Some("Hello, World!");
6059
// `Option::map` takes self *by value*, consuming `maybe_some_string`
@@ -83,6 +82,6 @@ Content("\n")
8382
Content("# ")
8483
Content("Examples")
8584
Content("\n")
86-
Content("\n```cairo\n")
85+
Content("```cairo\n")
8786
Content("let maybe_some_string: Option<ByteArray> = Some(\"Hello, World!\");\n// `Option::map` takes self *by value*, consuming `maybe_some_string`\nlet maybe_some_len = maybe_some_string.map(|s: ByteArray| s.len());\nassert!(maybe_some_len == Some(13));\n\nlet x: Option<ByteArray> = None;\nassert!(x.map(|s: ByteArray| s.len()) == None);\n")
8887
Content("```")

‎crates/cairo-lang-doc/src/tests/test-data/font_formatting.txt‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
//! > Documentation submodules
2+
3+
//! > test_runner_name
4+
documentation_test_runner
5+
6+
//! > cairo_project.toml
7+
[crate_roots]
8+
hello = "src"
9+
10+
//! > cairo_code
11+
//! Test **bold** inline.
12+
//!
13+
//! **Paragraph can be bold.
14+
//! And this will be a soft break.**
15+
//!
16+
//! **Paragraph can be bold.**
17+
//!
18+
//! And this will be a new paragraph.
19+
//!
20+
//! **Table will be correctly formatted after a bold paragraph.**
21+
//! |**C1**| C2|
22+
//! |---:|:---:|
23+
//! |R1C1|_R1C2_|
24+
//!
25+
//! _Can mix italic_ **and bold** inline.
26+
//! **_Can be_** _**both**_.
27+
//!
28+
//! _Paragraph can be italic.
29+
//! And this will be a soft break._
30+
//!
31+
//! _Paragraph can be italic._
32+
//!
33+
//! And this will be a new paragraph _**[link can bold italic](URL)**_.
34+
//!
35+
//! _Code block will be correctly formatted after an italic paragraph._
36+
//! ```
37+
//! fn new_Point() {
38+
//! Point {x: 12, y: 14}
39+
//! }
40+
//! ```
41+
42+
//! > Item signature #1
43+
44+
//! > Item documentation #1
45+
Test **bold** inline.
46+
47+
**Paragraph can be bold.
48+
And this will be a soft break.**
49+
50+
**Paragraph can be bold.**
51+
52+
And this will be a new paragraph.
53+
54+
**Table will be correctly formatted after a bold paragraph.**
55+
56+
|**C1**|C2|
57+
|---:|:---:|
58+
|R1C1|_R1C2_|
59+
60+
_Can mix italic_ **and bold** inline.
61+
**_Can be_** _**both**_.
62+
63+
_Paragraph can be italic.
64+
And this will be a soft break._
65+
66+
_Paragraph can be italic._
67+
68+
And this will be a new paragraph _**[link can bold italic](URL)**_.
69+
70+
_Code block will be correctly formatted after an italic paragraph._
71+
```cairo
72+
fn new_Point() {
73+
Point {x: 12, y: 14}
74+
}
75+
```
76+
77+
//! > Item documentation tokens #1
78+
Content("Test ")
79+
Content("**")
80+
Content("bold")
81+
Content("**")
82+
Content(" inline.")
83+
Content("\n")
84+
Content("\n")
85+
Content("**")
86+
Content("Paragraph can be bold.")
87+
Content("\n")
88+
Content("And this will be a soft break.")
89+
Content("**")
90+
Content("\n")
91+
Content("\n")
92+
Content("**")
93+
Content("Paragraph can be bold.")
94+
Content("**")
95+
Content("\n")
96+
Content("\n")
97+
Content("And this will be a new paragraph.")
98+
Content("\n")
99+
Content("\n")
100+
Content("**")
101+
Content("Table will be correctly formatted after a bold paragraph.")
102+
Content("**")
103+
Content("\n")
104+
Content("\n")
105+
Content("|")
106+
Content("**")
107+
Content("C1")
108+
Content("**")
109+
Content("|")
110+
Content("C2")
111+
Content("|\n|---:|:---:|")
112+
Content("\n")
113+
Content("|")
114+
Content("R1C1")
115+
Content("|")
116+
Content("_")
117+
Content("R1C2")
118+
Content("_")
119+
Content("|")
120+
Content("\n")
121+
Content("\n")
122+
Content("_")
123+
Content("Can mix italic")
124+
Content("_")
125+
Content(" ")
126+
Content("**")
127+
Content("and bold")
128+
Content("**")
129+
Content(" inline.")
130+
Content("\n")
131+
Content("**")
132+
Content("_")
133+
Content("Can be")
134+
Content("_")
135+
Content("**")
136+
Content(" ")
137+
Content("_")
138+
Content("**")
139+
Content("both")
140+
Content("**")
141+
Content("_")
142+
Content(".")
143+
Content("\n")
144+
Content("\n")
145+
Content("_")
146+
Content("Paragraph can be italic.")
147+
Content("\n")
148+
Content("And this will be a soft break.")
149+
Content("_")
150+
Content("\n")
151+
Content("\n")
152+
Content("_")
153+
Content("Paragraph can be italic.")
154+
Content("_")
155+
Content("\n")
156+
Content("\n")
157+
Content("And this will be a new paragraph ")
158+
Content("_")
159+
Content("**")
160+
CommentLinkToken { label: "link can bold italic", path: Some("URL"), resolved_item_name: None }
161+
Content("**")
162+
Content("_")
163+
Content(".")
164+
Content("\n")
165+
Content("\n")
166+
Content("_")
167+
Content("Code block will be correctly formatted after an italic paragraph.")
168+
Content("_")
169+
Content("\n")
170+
Content("```cairo\n")
171+
Content(" fn new_Point() {\n Point {x: 12, y: 14}\n }\n")
172+
Content("```")

‎crates/cairo-lang-doc/src/tests/test-data/rules_formatting.txt‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,16 @@ And this shouldn't work.
3535

3636
//! > Item documentation tokens #1
3737
Content("Use three or more asterisks, dashes, or underscores in one lines.")
38-
Content("\n___\n")
38+
Content("\n")
39+
Content("___\n")
3940
Content("\n")
4041
Content("Without blank lines, this would be a heading.")
41-
Content("\n___\n")
42+
Content("\n")
43+
Content("___\n")
4244
Content("\n")
4345
Content("This is also a valid way to create a horizontal rule.")
44-
Content("\n___\n")
46+
Content("\n")
47+
Content("___\n")
4548
Content("\n")
4649
Content("And this shouldn't work.")
4750
Content("\n")

‎crates/cairo-lang-doc/src/tests/test-data/submodule.txt‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,8 @@ So don't even try.
7575

7676
//! > Item documentation tokens #1
7777
Content("This is a testing crate file. It's for the tests purposes only.")
78-
Content("\n```cairo\n")
78+
Content("\n")
79+
Content("```cairo\n")
7980
Content(" let a = 5;\n")
8081
Content("```\n")
8182
Content("\n")
@@ -117,7 +118,8 @@ Content("\n")
117118
Content("Testing purposes only!")
118119
Content(" ")
119120
Content("This one is just a prefix comment for a module.")
120-
Content("\n```rust\n")
121+
Content("\n")
122+
Content("```rust\n")
121123
Content(" let a = String::from(\"This also works fine\");\n")
122124
Content("```\n")
123125
Content("\n")
@@ -162,5 +164,6 @@ CommentLinkToken { label: "cairo_submodule_code::inner_sub_module", path: None,
162164
Content(".")
163165
Content(" ")
164166
Content("Empty code example.")
165-
Content("\n```rust\n")
167+
Content("\n")
168+
Content("```rust\n")
166169
Content("```")

‎crates/cairo-lang-doc/src/tests/test-data/tables_formatting.txt‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ A more complicated real case study from corelib.
4747

4848
//! > Item documentation tokens #1
4949
Content("simple table with alignment")
50-
Content("\n\n")
50+
Content("\n")
51+
Content("\n")
5152
Content("|")
5253
Content("C1")
5354
Content("|")
@@ -68,7 +69,8 @@ Content("|")
6869
Content("\n")
6970
Content("\n")
7071
Content("A more complicated real case study from corelib.")
71-
Content("\n\n")
72+
Content("\n")
73+
Content("\n")
7274
Content("|")
7375
Content("method")
7476
Content("|")

‎crates/cairo-lang-doc/src/tests/test.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ cairo_lang_test_utils::test_file_test!(
2727
lists_formatting: "lists_formatting.txt",
2828
tables_formatting: "tables_formatting.txt",
2929
rules_formatting: "rules_formatting.txt",
30+
font_formatting: "font_formatting.txt",
3031
},
3132
documentation_test_runner
3233
);

0 commit comments

Comments
 (0)