Crate yadr 

Parsing logic for Y-Statement ADRs in source code comments.

These ADRs take the form:

/*
 * YADR: 2023-11-28 some-title
 *
 * In the context of <use case/user story u>, we faced <concern c>.
 *
 * We decided for <option o>, and neglected <other options>.
 *
 * We did this to achieve <system qualities/desired consequences>, accepting <downside
 * d/undesired consequences>.
 *
 * We think this is the right trade-off because <additional rationale>.
 */

and should be used to concisely convey important architectural decisions in software projects. For example, here is one taken from the dson crate:

/*
 * YADR: 2024-06-18 Array elements without a position defined
 *
 * In the context of dealing with array elements which don't have a position defined,
 * we faced a decision of how to expose these elements through the public OrArray API.
 *
 * We decided for assigning these elements an arbitrary but deterministic position, as
 * a function of their uid, and neglected to attempt to map them to the start or end of
 * the array, or provide a separate API for access to position-less elements, when their
 * uid is not yet known.
 *
 * We did this to achieve minimal impact to the user-facing API, to avoid increasing the
 * cognitive burden of using this crate, and to ensure that every node has a consistent
 * view of the array when they share the same state, accepting that users may be
 * surprised to find that a non-move operation (like a delete) can result in an element
 * being assigned a different position.
 *
 * We think this is the right trade-off because this is a rare edge case, and placing
 * the burden of handling it on users (by providing a separate access interface)
 * would've been unreasonable. Additionally, non-deterministic views of the array would
 * have violated a core assumption that nodes in sync with each other have the same view
 * of the state.
 */

Note that we diverge slightly from the original Y-Statement format to make the comment easier to digest!

Errors

Everything here reports failures as miette::Report rather than as a bespoke error enum, which is a deliberate departure from the usual advice to expose a concrete, matchable error type.

The reason is that a failure here is a diagnostic, not a condition to branch on. Each one carries the span of the offending text, a suggestion for how to fix it, and the surrounding source, so that a caller can render something a human can act on. That is the entire value of the error, and there is very little a caller could sensibly do differently on the strength of knowing which paragraph failed to parse. An enum would either have to throw that information away or wrap it, and callers would be no better off.

Structs

UnknownLanguage

The error returned when a string does not name a Language that yadr can parse.

YAdr

A parsed Y-Statement ADR.

Enums

Language

The language of a source file.

Functions

find_all

Invokes on_yadr for each Y-Statement ADR contained in source code comments in input.