changeset 41184:dcf818267bc1

rust-cpython: rustdoc improvements

By default, `cargo doc` builds the documentation for public
constructs only, so we make public those that can. Since `cindex`
is not safe, we keep it private.

Unfortunately, the macro syntax of rust-cpython doesn't allow us
to document the classes directly, so we resort to do that at
the module level.

Differential Revision: https://phab.mercurial-scm.org/D5546

--- a/rust/hg-cpython/src/ancestors.rs	Thu Jan 10 10:23:22 2019 -0500
+++ b/rust/hg-cpython/src/ancestors.rs	Sat Dec 22 11:38:03 2018 +0100
@@ -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)?;

--- a/rust/hg-cpython/src/exceptions.rs	Thu Jan 10 10:23:22 2019 -0500
+++ b/rust/hg-cpython/src/exceptions.rs	Sat Dec 22 11:38:03 2018 +0100
@@ -1,3 +1,15 @@
+// ancestors.rs
+//
+// Copyright 2018 Georges Racinet <[e-mail]>
+//
+// 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;

--- a/rust/hg-cpython/src/lib.rs	Thu Jan 10 10:23:22 2019 -0500
+++ b/rust/hg-cpython/src/lib.rs	Sat Dec 22 11:38:03 2018 +0100
@@ -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(