Chapter 12½: inside tree/src

lib.rs, top to bottom: the types (Kind, Entry, Body, Contents); Raw, the private shape GitHub's JSON is read into; parse; media_type; the path helpers (segments, encoded, parent); then the renderer (Heading, Rendered, markdown, slug, agents, link).

markdown is worth reading on its own. It runs pulldown-cmark's parser, rewrites links and images and turns raw HTML into text in one pass, gives headings their anchors in a second, and swaps mermaid code blocks for <pre class="mermaid"> in a third, before writing HTML.

annotate.rs is how a source file becomes the page you read it on. It lexes the whole file first (comments, strings, keywords, types, calls), and only then cuts it wherever whole-line comments begin, so a line that merely looks like a comment inside a string stays code. Each run of comments is handed to markdown; the code under it keeps its line numbers.

A comment speaks for the item under it and no further. After a blank line, code that begins no deeper than that item is its own section with nothing beside it, so a struct nobody documented is not shown next to the comment of the constant above it. And a remark in the middle of a function, straight after a line of code, stays in the function: only a comment at the margin, a doc comment (///), or in other languages one after a blank line, opens a section.

Aside. This is Docco's idea (Jeremy Ashkenas, 2010): nobody reads a wall of code, but most people will read a paragraph with the code it is about beside it. Rust's doc comments are already markdown, so here the left column is simply what the authors wrote.

tests.rs holds the promises: folders before files, no token kept, a binary file kept as bytes, a path cannot climb out, relative links stay in the code pages, raw HTML stays text, anchors are unique, diagrams stay escaped.

Try it. cargo test -p tree.

← Previous: Chapter 12, tree/ · Up: tree · Next: Chapter 13, tools/ →