Improve crate docs

README.md

@@ -33,7 +33,29 @@ There are some actual usages of it as well which can be also used as an example:
 * in [blocksense-network/noir: their tracing support for CodeTracer](https://github.com/blocksense-network/noir/tree/blocksense/tooling/tracer)
 * in a small toy interpreter to be released as a part of the CodeTracer repo
 
-One can always directly produce the same traces from various languages. We're open for cooperation or discussion on usecases! 
+One can always directly produce the same traces from various languages. We're open for cooperation or discussion on usecases!
+
+### Building the Documentation
+
+The library API docs can be built locally with:
+
+```bash
+cargo doc --all-features --no-deps
+```
+
+The generated HTML documentation will be placed under `target/doc`. Open
+`target/doc/runtime_tracing/index.html` in a browser to inspect it.
+
+### Publishing to crates.io
+
+After updating the version number in `Cargo.toml`, publish a new release with:
+
+```bash
+cargo publish
+```
+
+Documentation for released versions will be automatically hosted on
+[docs.rs](https://docs.rs/runtime_tracing).
 
 ### Legal
 

src/lib.rs

@@ -3,6 +3,11 @@
 // but i might be wrong
 // also for now, allowing it to pass `cargo clippy`
 #![allow(clippy::from_over_into)]
+//! Runtime tracing structures and helpers for the CodeTracer debugger.
+//!
+//! This crate provides the [`Tracer`] type for emitting trace events and a
+//! collection of serializable structures describing the trace format.
+//! The format is documented in `docs/` and the README.
 mod tracer;
 mod types;
 pub use crate::tracer::{Tracer, NONE_TYPE_ID, NONE_VALUE};

src/tracer.rs

@@ -1,3 +1,5 @@
+//! Helper for generating trace events from a running program or interpreter.
+
 use std::collections::HashMap;
 use std::env;
 use std::error::Error;
@@ -11,6 +13,10 @@ use crate::types::{
 };
 use crate::RValue;
 
+/// State machine used to record [`TraceLowLevelEvent`]s.
+///
+/// A `Tracer` instance accumulates events and can store them on disk via the
+/// `store_trace_*` methods.
 pub struct Tracer {
     // trace metadata:
     workdir: PathBuf,
@@ -40,6 +46,7 @@ pub const NONE_VALUE: ValueRecord = ValueRecord::None { type_id: NONE_TYPE_ID };
 pub const TOP_LEVEL_FUNCTION_ID: FunctionId = FunctionId(0);
 
 impl Tracer {
+    /// Create a new tracer instance for the given program and arguments.
     pub fn new(program: &str, args: &[String]) -> Self {
         Tracer {
             workdir: env::current_dir().expect("can access the current dir"),
@@ -56,6 +63,7 @@ impl Tracer {
         }
     }
 
+    /// Begin tracing of a program starting at the given source location.
     pub fn start(&mut self, path: &Path, line: Line) {
         let function_id = self.ensure_function_id("<toplevel>", path, line);
         self.register_call(function_id, vec![]);

src/types.rs

@@ -1,3 +1,7 @@
+//! Serializable record types for the trace format used by CodeTracer.
+//!
+//! All structures derive [`serde::Serialize`] and [`serde::Deserialize`].
+
 use std::cmp::Ord;
 use std::ops;
 use std::path::PathBuf;
@@ -12,6 +16,7 @@ use serde_repr::*;
 // afterwards in postprocessing
 // this assumption can change in the future
 
+/// Low level building blocks that make up a recorded trace.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum TraceLowLevelEvent {
     Step(StepRecord),
@@ -321,6 +326,7 @@ impl Into<usize> for TypeId {
 // use value::Value for interaction with existing frontend
 // TODO: convert between them or
 // serialize ValueRecord in a compatible way?
+/// Representation of a runtime value captured in a trace.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(tag = "kind")]
 pub enum ValueRecord {
@@ -382,6 +388,7 @@ pub enum ValueRecord {
     },
 }
 
+/// Categories of types recorded in the trace.
 #[derive(Debug, Default, Copy, Clone, FromPrimitive, Serialize_repr, Deserialize_repr, PartialEq)]
 #[repr(u8)]
 pub enum TypeKind {
@@ -440,6 +447,7 @@ pub enum TypeKind {
     Slice,
 }
 
+/// Kinds of I/O or log events that can appear in a trace.
 #[derive(Debug, Default, Copy, Clone, FromPrimitive, Serialize_repr, Deserialize_repr, PartialEq)]
 #[repr(u8)]
 pub enum EventLogKind {