D5546: rust-cpython: rustdoc improvements

[gracinet (Georges Racinet)]

This revision was automatically updated to reflect the committed changes.
Closed by commit rHGdcf818267bc1: rust-cpython: rustdoc improvements (authored by gracinet, committed by ).

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D5546?vs=13124&id=13170

REVISION DETAIL
  https://phab.mercurial-scm.org/D5546

AFFECTED FILES
  rust/hg-cpython/src/ancestors.rs
  rust/hg-cpython/src/exceptions.rs
  rust/hg-cpython/src/lib.rs

CHANGE DETAILS

diff --git a/rust/hg-cpython/src/lib.rs b/rust/hg-cpython/src/lib.rs
--- a/rust/hg-cpython/src/lib.rs
+++ b/rust/hg-cpython/src/lib.rs
@@ -12,7 +12,8 @@
 //! it behaves as the `cext` package.
 //!
 //! Example:
-//! ```
+//!
+//! ```text
 //! >>> from mercurial.rustext import ancestor
 //! >>> ancestor.__doc__
 //! 'Generic DAG ancestor algorithms - Rust implementation'
@@ -23,9 +24,9 @@
 extern crate hg;
 extern crate libc;
 
-mod ancestors;
+pub mod ancestors;
 mod cindex;
-mod exceptions;
+pub mod exceptions;
 
 py_module_initializer!(rustext, initrustext, PyInit_rustext, |py, m| {
     m.add(
diff --git a/rust/hg-cpython/src/exceptions.rs b/rust/hg-cpython/src/exceptions.rs
--- a/rust/hg-cpython/src/exceptions.rs
+++ b/rust/hg-cpython/src/exceptions.rs
@@ -1,3 +1,15 @@
+// ancestors.rs
+//
+// Copyright 2018 Georges Racinet <gracinet at anybox.fr>
+//
+// This software may be used and distributed according to the terms of the
+// GNU General Public License version 2 or any later version.
+
+//! Bindings for Rust errors
+//!
+//! [`GraphError`] exposes `hg::GraphError` as a subclass of `ValueError`
+//!
+//! [`GraphError`]: struct.GraphError.html
 use cpython::exc::ValueError;
 use cpython::{PyErr, Python};
 use hg;
diff --git a/rust/hg-cpython/src/ancestors.rs b/rust/hg-cpython/src/ancestors.rs
--- a/rust/hg-cpython/src/ancestors.rs
+++ b/rust/hg-cpython/src/ancestors.rs
@@ -5,8 +5,23 @@
 // This software may be used and distributed according to the terms of the
 // GNU General Public License version 2 or any later version.
 
-//! Bindings for the hg::ancestors module provided by the
+//! Bindings for the `hg::ancestors` module provided by the
 //! `hg-core` crate. From Python, this will be seen as `rustext.ancestor`
+//! and can be used as replacement for the the pure `ancestor` Python module.
+//!
+//! # Classes visible from Python:
+//! - [`LazyAncestors`] is the Rust implementation of
+//!   `mercurial.ancestor.lazyancestors`.
+//!   The only difference is that it is instantiated with a C `parsers.index`
+//!   instance instead of a parents function.
+//!
+//! - [`AncestorsIterator`] is the Rust counterpart of the
+//!   `ancestor._lazyancestorsiter` Python generator.
+//!   From Python, instances of this should be mainly obtained by calling
+//!   `iter()` on a [`LazyAncestors`] instance.
+//!
+//! [`LazyAncestors`]: struct.LazyAncestors.html
+//! [`AncestorsIterator`]: struct.AncestorsIterator.html
 use cindex::Index;
 use cpython::{
     ObjectProtocol, PyClone, PyDict, PyModule, PyObject, PyResult, Python,
@@ -19,16 +34,16 @@
 
 /// Utility function to convert a Python iterable into a Vec<Revision>
 ///
-/// We need this to feed to AncestorIterators constructors because
-/// a PyErr can arise at each step of iteration, whereas our inner objects
-/// expect iterables over Revision, not over some Result<Revision, PyErr>
+/// We need this to feed to `AncestorIterators` constructors because
+/// a `PyErr` can arise at each step of iteration, whereas our inner objects
+/// expect iterables over `Revision`, not over some `Result<Revision, PyErr>`
 fn reviter_to_revvec(py: Python, revs: PyObject) -> PyResult<Vec<Revision>> {
     revs.iter(py)?
         .map(|r| r.and_then(|o| o.extract::<Revision>(py)))
         .collect()
 }
 
-py_class!(class AncestorsIterator |py| {
+py_class!(pub class AncestorsIterator |py| {
     // TODO RW lock ?
     data inner: RefCell<Box<CoreIterator<Index>>>;
 
@@ -70,7 +85,7 @@
     }
 }
 
-py_class!(class LazyAncestors |py| {
+py_class!(pub class LazyAncestors |py| {
     data inner: RefCell<Box<CoreLazy<Index>>>;
 
     def __contains__(&self, rev: Revision) -> PyResult<bool> {
@@ -101,7 +116,7 @@
 
 });
 
-/// Create the module, with __package__ given from parent
+/// Create the module, with `__package__` given from parent
 pub fn init_module(py: Python, package: &str) -> PyResult<PyModule> {
     let dotted_name = &format!("{}.ancestor", package);
     let m = PyModule::new(py, dotted_name)?;



To: gracinet, #hg-reviewers
Cc: durin42, kevincox, mercurial-devel