From 90d25e74c403c70ecf0cdb5288df348fcce93a15 Mon Sep 17 00:00:00 2001
From: Andrea Lattuada <andrea@lattuada.me>
Date: Tue, 28 May 2019 11:15:27 +0200
Subject: [PATCH] Add docs, prepare release

Signed-off-by: Andrea Lattuada <andrea.lattuada@inf.ethz.ch>
---
 tdiag/release.toml          |  6 ++++++
 tdiag/src/commands/graph.rs | 11 +++++++++++
 tdiag/src/commands/mod.rs   |  6 ++++++
 tdiag/src/lib.rs            |  5 +++++
 tdiag/src/main.rs           |  5 +++++
 5 files changed, 33 insertions(+)
 create mode 100644 tdiag/release.toml

diff --git a/tdiag/release.toml b/tdiag/release.toml
new file mode 100644
index 0000000..1b40ae2
--- /dev/null
+++ b/tdiag/release.toml
@@ -0,0 +1,6 @@
+upload-doc = false
+tag-prefix = "v"
+pre-release-commit-message = "[tdiag] Release version {{version}}"
+pro-release-commit-message = "[tdiag] Development version {{next_version}}"
+tag-message = "version {{version}}"
+dev-version-ext = "pre"
diff --git a/tdiag/src/commands/graph.rs b/tdiag/src/commands/graph.rs
index a970571..6b41557 100644
--- a/tdiag/src/commands/graph.rs
+++ b/tdiag/src/commands/graph.rs
@@ -1,3 +1,5 @@
+//! "graph" subcommand: browser-based tool to display the dataflow graph.
+
 use std::sync::{Arc, Mutex};
 
 use crate::DiagError;
@@ -14,6 +16,15 @@ use tdiag_connect::receive::ReplayWithShutdown;
 
 static GRAPH_HTML: &str = include_str!("graph/dataflow-graph.html");
 
+/// Creates an html file that renders a timely dataflow graph.
+///
+/// 1. Listens to incoming connection from a timely-dataflow program with
+/// logging enabled;
+/// 2. runs a differential-dataflow program to reconstruct the source
+/// computation's dataflow graph;
+/// 3. writes an html file that renders the dataflow graph.
+///
+/// This module includes `graph/dataflow-graph.html` as a static resource.
 pub fn listen_and_render(
     timely_configuration: timely::Configuration,
     sockets: Vec<Option<std::net::TcpStream>>,
diff --git a/tdiag/src/commands/mod.rs b/tdiag/src/commands/mod.rs
index 6f94350..0a739a3 100644
--- a/tdiag/src/commands/mod.rs
+++ b/tdiag/src/commands/mod.rs
@@ -1 +1,7 @@
+//! Subcommand modules.
+//!
+//! Each of the program's subcommand logic is in a separate module here.
+//!
+//! Subfolders in the source tree contain resource files.
+
 pub mod graph;
diff --git a/tdiag/src/lib.rs b/tdiag/src/lib.rs
index 17aa3a5..90fef42 100644
--- a/tdiag/src/lib.rs
+++ b/tdiag/src/lib.rs
@@ -1,5 +1,10 @@
+//! Tools to inspect a timely-dataflow computation.
+
+#![deny(missing_docs)]
+
 pub mod commands;
 
+/// An error generated by one of the commands of this tool.
 pub struct DiagError(pub String);
 
 impl From<std::io::Error> for DiagError {
diff --git a/tdiag/src/main.rs b/tdiag/src/main.rs
index c0ec1ed..676cd88 100644
--- a/tdiag/src/main.rs
+++ b/tdiag/src/main.rs
@@ -1,3 +1,8 @@
+//! Command-line tools (with browser-based visualization)
+//! to inspect a timely-dataflow computation.
+//!
+//! See the README and --help for usage information.
+
 use tdiag::*;
 
 fn run() -> Result<(), DiagError> {