1# Chapter 12½: inside tree/src
2
3`lib.rs`, top to bottom: the types (`Kind`, `Entry`, `Body`, `Contents`);
4`Raw`, the private shape GitHub's JSON is read into; `parse`; `media_type`;
5the path helpers (`segments`, `encoded`, `parent`); then the renderer
6(`Heading`, `Rendered`, `markdown`, `slug`, `agents`, `link`).
7
8`markdown` is worth reading on its own. It runs pulldown-cmark's parser,
9rewrites links and images and turns raw HTML into text in one pass, gives
10headings their anchors in a second, and swaps mermaid code blocks for
11`<pre class="mermaid">` in a third, before writing HTML.
12
13`annotate.rs` is how a source file becomes the page you read it on. It
14lexes the whole file first (comments, strings, keywords, types, calls), and
15only then cuts it wherever whole-line comments begin, so a line that merely
16looks like a comment inside a string stays code. Each run of comments is
17handed to `markdown`; the code under it keeps its line numbers.
18
19A comment speaks for the item under it and no further. After a blank line,
20code that begins no deeper than that item is its own section with nothing
21beside it, so a struct nobody documented is not shown next to the comment
22of the constant above it. And a remark in the middle of a function, straight
23after a line of code, stays in the function: only a comment at the margin,
24a doc comment (`///`), or in other languages one after a blank line, opens
25a section.
26
27> **Aside.** This is Docco's idea (Jeremy Ashkenas, 2010): nobody reads a
28> wall of code, but most people will read a paragraph with the code it is
29> about beside it. Rust's doc comments are already markdown, so here the
30> left column is simply what the authors wrote.
31
32`tests.rs` holds the promises: folders before files, no token kept, a
33binary file kept as bytes, a path cannot climb out, relative links stay in
34the code pages, raw HTML stays text, anchors are unique, diagrams stay
35escaped.
36
37> **Try it.** `cargo test -p tree`.
38
39| File | What |
40| --- | --- |
41| [lib.rs](lib.rs) | Parsing GitHub's contents API, paths, and markdown. |
42| [annotate.rs](annotate.rs) | A source file as Docco reads it: `lex` colours it, `sections` puts each run of comments beside the code under it. |
43| [icons.rs](icons.rs), [icons_theme.rs](icons_theme.rs) | Which pixel icon a file or folder gets: the icon theme's own map (generated), and the few names it has never met. |
44| [tests.rs](tests.rs) | What it parses, refuses and renders. |
45
46← Previous: [Chapter 12, tree/](../) · Up: [tree](../) · Next: [Chapter 13, tools/](../../../tools/) →