Skip to content

Commit 2f12c33

Browse files
author
Zibi Braniecki
committed
Finish documentation
1 parent 1ebe11e commit 2f12c33

File tree

7 files changed

+380
-12
lines changed

7 files changed

+380
-12
lines changed

‎README.md

+56-3
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,28 @@
77
[![Coverage Status](https://coveralls.io/repos/github/zbraniecki/annotate-snippets-rs/badge.svg?branch=master)](https://coveralls.io/github/zbraniecki/annotate-snippets-rs?branch=master)
88

99
The library helps visualize meta information annotating source code slices.
10+
It takes a data structure called `Snippet` on the input and procudes a `String`
11+
which may look like this:
12+
13+
```text
14+
error[E0308]: mismatched types
15+
--> src/format.rs:52:1
16+
|
17+
51 | ) -> Option<String> {
18+
| -------------- expected `Option<String>` because of return type
19+
52 | / for ann in annotations {
20+
53 | | match (ann.range.0, ann.range.1) {
21+
54 | | (None, None) => continue,
22+
55 | | (Some(start), Some(end)) if start > end_index => continue,
23+
... |
24+
71 | | }
25+
72 | | }
26+
| |_____^ expected enum `std::option::Option`, found ()
27+
```
1028

1129
[Documentation][]
1230

13-
[Documentation]: https://docs.rs/annotate-snippets-rs/
31+
[Documentation]: https://docs.rs/annotate-snippets/
1432

1533
Installation
1634
------------
@@ -30,8 +48,43 @@ extern crate annotate_snippets;
3048
use annotate_snippets::snippet;
3149

3250
fn main() {
33-
let snippet = Snippet {};
34-
println!("{}", snippet);
51+
let snippet = Snippet {
52+
title: Some(Annotation {
53+
label: Some("expected type, found `22`".to_string()),
54+
id: None,
55+
annotation_type: AnnotationType::Error,
56+
}),
57+
footer: vec![],
58+
slices: vec![
59+
Slice {
60+
source: r#"
61+
This is an example
62+
content of the slice
63+
which will be annotated
64+
with the list of annotations below.
65+
"#.to_string(),
66+
line_start: 26,
67+
origin: Some("examples/example.txt".to_string()),
68+
fold: false,
69+
annotations: vec![
70+
SourceAnnotation {
71+
label: "Example error annotation".to_string(),
72+
annotation_type: AnnotationType::Error,
73+
range: (13, 18),
74+
},
75+
SourceAnnotation {
76+
label: "and here's a warning".to_string(),
77+
annotation_type: AnnotationType::Warning,
78+
range: (34, 50),
79+
},
80+
],
81+
},
82+
],
83+
};
84+
85+
let dl = DisplayList::from(snippet);
86+
let dlf = DisplayListFormatter::new(true);
87+
dlf.format(&dl);
3588
}
3689
```
3790

‎src/display_list/from_snippet.rs

+1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
//! Trait for converting `Snippet` to `DisplayList`.
12
use super::*;
23
use snippet;
34

‎src/display_list/mod.rs

+120
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,123 @@
1+
//! display_list module stores the output model for the snippet.
2+
//!
3+
//! `DisplayList` is a central structure in the crate, which contains
4+
//! the structured list of lines to be displayed.
5+
//!
6+
//! It is made of two types of lines: `Source` and `Raw`. All `Source` lines
7+
//! are structured using four columns:
8+
//!
9+
//! ```text
10+
//! /------------ (1) Line number column.
11+
//! | /--------- (2) Line number column delimiter.
12+
//! | | /------- (3) Inline marks column.
13+
//! | | | /--- (4) Content column with the source and annotations for slices.
14+
//! | | | |
15+
//! =============================================================================
16+
//! error[E0308]: mismatched types
17+
//! --> src/format.rs:51:5
18+
//! |
19+
//! 151 | / fn test() -> String {
20+
//! 152 | | return "test";
21+
//! 153 | | }
22+
//! | |___^ error: expected `String`, for `&str`.
23+
//! |
24+
//! ```
25+
//!
26+
//! The first two lines of the example above are `Raw` lines, while the rest
27+
//! are `Source` lines.
28+
//!
29+
//! `DisplayList` does not store column alignment information, and those are
30+
//! only calculated by the `DisplayListFormatter` using information such as
31+
//! styling.
32+
//!
33+
//! The above snippet has been built out of the following structure:
34+
//!
35+
//! ```
36+
//! use annotate_snippets::display_list::*;
37+
//!
38+
//! let dl = DisplayList {
39+
//! body: vec![
40+
//! DisplayLine::Raw(DisplayRawLine::Annotation {
41+
//! annotation: Annotation {
42+
//! annotation_type: DisplayAnnotationType::Error,
43+
//! id: Some("E0308".to_string()),
44+
//! label: vec![
45+
//! DisplayTextFragment {
46+
//! content: "mismatched types".to_string(),
47+
//! style: DisplayTextStyle::Regular,
48+
//! }
49+
//! ]
50+
//! },
51+
//! source_aligned: false,
52+
//! continuation: false,
53+
//! }),
54+
//! DisplayLine::Raw(DisplayRawLine::Origin {
55+
//! path: "src/format.rs".to_string(),
56+
//! pos: Some((51, 5)),
57+
//! header_type: DisplayHeaderType::Initial,
58+
//! }),
59+
//! DisplayLine::Source {
60+
//! lineno: Some(151),
61+
//! inline_marks: vec![
62+
//! DisplayMark {
63+
//! mark_type: DisplayMarkType::AnnotationStart,
64+
//! annotation_type: DisplayAnnotationType::Error,
65+
//! }
66+
//! ],
67+
//! line: DisplaySourceLine::Content {
68+
//! text: " fn test() -> String {".to_string(),
69+
//! range: (0, 24)
70+
//! }
71+
//! },
72+
//! DisplayLine::Source {
73+
//! lineno: Some(152),
74+
//! inline_marks: vec![
75+
//! DisplayMark {
76+
//! mark_type: DisplayMarkType::AnnotationThrough,
77+
//! annotation_type: DisplayAnnotationType::Error,
78+
//! }
79+
//! ],
80+
//! line: DisplaySourceLine::Content {
81+
//! text: " return \"test\";".to_string(),
82+
//! range: (25, 46)
83+
//! }
84+
//! },
85+
//! DisplayLine::Source {
86+
//! lineno: Some(153),
87+
//! inline_marks: vec![
88+
//! DisplayMark {
89+
//! mark_type: DisplayMarkType::AnnotationThrough,
90+
//! annotation_type: DisplayAnnotationType::Error,
91+
//! }
92+
//! ],
93+
//! line: DisplaySourceLine::Content {
94+
//! text: " }".to_string(),
95+
//! range: (47, 51)
96+
//! }
97+
//! },
98+
//! DisplayLine::Source {
99+
//! lineno: None,
100+
//! inline_marks: vec![],
101+
//! line: DisplaySourceLine::Annotation {
102+
//! annotation: Annotation {
103+
//! annotation_type: DisplayAnnotationType::Error,
104+
//! id: None,
105+
//! label: vec![
106+
//! DisplayTextFragment {
107+
//! content: "expected `String`, for `&str`.".to_string(),
108+
//! style: DisplayTextStyle::Regular,
109+
//! }
110+
//! ]
111+
//! },
112+
//! range: (3, 4),
113+
//! annotation_type: DisplayAnnotationType::Error,
114+
//! annotation_part: DisplayAnnotationPart::MultilineEnd,
115+
//! }
116+
//!
117+
//! }
118+
//! ]
119+
//! };
120+
//! ```
1121
mod from_snippet;
2122
mod structs;
3123

0 commit comments

Comments
 (0)