4.2. Documentation

The Tic Tac Toe library provides API documentation to help developers use the functionality provided by the library. This section describes how the documentation is put together and published.

4.2.1. Documentation Comments

Rust supports storing the library’s documentation along side the source code using documentation comments. 1 Each public item provided by the library has corresponding documentation that describes why the item should be used.

Common sections include examples, panics, and errors. In particular, Rust encourages every public type to have a corresponding example. The example for the library’s top level module shows a getting started example that is a simple yet complete Tic Tac Toe game that uses the APIs provided by the library. Additionally, the example code is exercised as part of the library’s tests which help developers detect if a public API has changed.

The Continuous Integration system is configured to ensure all public items are documented. Any public item that is not documented causes a build error to be reported.

Related Requirements

• Stable Library API

• Detailed Library Documentation

• Getting Started Example

4.2.2. Change Log

The library’s source code repository includes a CHANGELOG.md file that describes user visible changes to the library. For each release a new entry is added to the change log that describes changes users might care about. 2 The change log also mentions how the library follows semantic versioning. 3

Related Requirements

• Stable Library API

4.2.3. Hosting

The packages’s Cargo.toml uses the default documentation value which means when the package is uploaded to crates.io, https://docs.rs automatically builds and hosts the library’s documentation.

The library’s source code repository README.md file contains a link to this documentation so developers can review the documentation without needing to download and build the documentation themselves.

Related Requirements

• Detailed Library Documentation

Footnotes

1

See the Making Useful Documentation Comments section in the Rust Book which is part of [Rust-Docs]. Additionally, there is a Documentation section in the [Rust-API-Guidelines].

2

See https://keepachangelog.com/ for the format of the CHANGELOG.md file and additional details / motivation for keeping a change log.

3

Rust RFC 1105 API Evolution describes semantic versioning as understood by Rust.