Mercurial > public > mercurial-scm > hg-stable

diff rust/hg-cpython/src/ancestors.rs @ 41184:dcf818267bc1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
author Georges Racinet <georges.racinet@octobus.net>
date Sat, 22 Dec 2018 11:38:03 +0100
parents b31a41f24864
children 5ac61ca58c3f
line wrap: on
line diff
--- 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)?;