Update docs (#93)

Fix broken doc link for Tree::traverse_nodes. 

update README

update crate-level docs

Author: molpopgen

README.md

@@ -8,11 +8,7 @@ This package provides the following:
 
 1. Low-level bindings to the C API of both `tskit` and `kastore`.
    We use [bindgen](https://docs.rs/bindgen) to automatically generate the bindings.
-2. The struct `tskit::TableCollection`, which wraps
-   `tsk_table_collection_t`. The wrapper is currently
-   incomplete, supporting only node, edge, site,
-   mutation, and population tables.  The remaining
-   tables will happen "soon".
+2. Support for table collections, tree sequences, and tree iteration.
 3. An error handling system that maps `tskit` error
    codes to `rust` errors while preserving error messages.
 
@@ -26,8 +22,6 @@ The overview is:
 The result is a `rust` library with all of these two C libraries statically compiled in.
 Further, `rust` types and functions exist in the module name `tskit::bindings`, allowing `unsafe` access to the low-level API.
 
-In the future, we hope to develop a more "rusty" front-end, hiding the `unsafe` bits from client code.
-
 Help wanted!
 
 ## Quick start guide

src/lib.rs

@@ -1,4 +1,34 @@
 //! A rust interface to [tskit](https://github.com/tskit-dev/tskit).
+//!
+//! This crate provides a mapping of the `tskit` C API to rust.
+//! The result is an interface similar to the `tskit` Python interface,
+//! but with all operations implemented using compiled code.
+//!
+//! # Features
+//!
+//! ## Interface to the C library
+//!
+//! * [`TableCollection`] wraps `tsk_table_collection_t`.
+//! * [`TreeSequence`] wraps `tsk_treeseq_t`.
+//! * [`Tree`] wraps `tsk_tree_t`. 
+//! * Tree iteration occurs via traits from [streaming_iterator](https://docs.rs/streaming-iterator/).
+//! * Errors returned from C map to [`TskitError::ErrorCode`]. 
+//!   Their string messages can be obtained by printing the error type.
+//!
+//! ## Safety
+//!
+//! * The types listed above handle all the memory management!
+//! * All array accesses are range-checked.
+//! * Object lifetimes are clear:
+//!     * Creating a tree sequence moves/consumes a table collection.
+//!     * Tree lifetimes are tied to that of the parent tree sequence.
+//!     * Table objects ([`NodeTable`], etc..) are only represented by non-owning, immutable types.
+//!
+//! # What is missing?
+//!
+//! * A lot of wrappers to the C functions.
+//! * Support for provenance tables.
+//! * Tree sequence statistics!
 
 #![allow(non_upper_case_globals)]
 #![allow(non_camel_case_types)]

src/table_collection.rs

@@ -109,8 +109,6 @@ use ll_bindings::tsk_table_collection_free;
 /// 1. Support all table types.  Currently, we only support
 ///    those needed for current goals in ongoing projects.
 /// 2. Strengthen some of the error handling.
-///
-/// Addressing point 3 may require API breakage.
 pub struct TableCollection {
     inner: Box<ll_bindings::tsk_table_collection_t>,
 }

src/trees.rs

@@ -290,7 +290,7 @@ impl Tree {
     ///
     /// # Errors
     ///
-    /// [`TskitError`] may be returned via [`Tree::nodes`].
+    /// [`TskitError`] may be returned via [`Tree::traverse_nodes`].
     pub fn total_branch_length(&self, by_span: bool) -> Result<f64, TskitError> {
         let nt = self.node_table();
         let mut b = 0.;
@@ -388,7 +388,7 @@ impl streaming_iterator::DoubleEndedStreamingIterator for Tree {
 }
 
 /// Specify the traversal order used by
-/// [`Tree::nodes`].
+/// [`Tree::traverse_nodes`].
 pub enum NodeTraversalOrder {
     ///Preorder traversal, starting at the root(s) of a [`Tree`].
     ///For trees with multiple roots, start at the left root,