rust: improve some comments

rust/src/lib.rs

@@ -3,10 +3,6 @@
 //!
 //! The bindings are still incomplete, and a work in progress.
 //!
-//! There is also the [notcurses](https://crates.io/crates/notcurses) crate,
-//! for a safer, more idiomatic wrapper, and with higher level abstractions,
-//! but also still very much more incomplete.
-//!
 //! # Ways of using this library
 //!
 //! The *rusty* way is to use the provided methods and constructors:
@@ -16,8 +12,8 @@
 //! fn main() -> NcResult<()> {
 //!     let nc = Notcurses::without_altscreen()?;
 //!     let plane = nc.stdplane()?;
-//!     plane.putstr("hello world");
-//!     nc.render();
+//!     plane.putstr("hello world")?;
+//!     nc.render()?;
 //!     nc.stop()?;
 //!     Ok(())
 //! }
@@ -73,10 +69,7 @@
 //! }
 //!
 //! ```
-//! ## Limitations of this library
-//!
-//! There are several common patterns in Rust that this library doesn't employ,
-//! and focuses instead on remaining at a closer distance to the C API.
+//! ## About this library
 //!
 //! 1. There are no Drop trait implementations, therefore you must manually stop
 //! each context before it goes out of scope ([Notcurses], [NcDirect]), and
@@ -86,14 +79,8 @@
 //! aliased to [NcIntResult]. But the Rust style methods handle errors more
 //! idiomatically using [NcResult] and [NcError].
 //!
-//! The [notcurses]() crate will use higher level abstractions in ways this
-//! library can not do.
-//!
-//! ### Things this library does do
 //!
-//! - Type aliases every underlying C type to leverage type checking.
-//! - Renames types to enforce regularity and consistency. (e.g. [NcCell])
-//! - Has handy macros for common tasks like [sleep!], [cstring!] & [error!].
+//! [Macros][#macros] are
 //!
 //! ## The `notcurses` C API docs
 //!

rust/src/macros.rs

@@ -1,10 +1,11 @@
 //! Macros
 //!
-//! NOTE: Use full paths everywhere. Don't assume anything will be in scope.
+//
+// NOTE: Use full paths everywhere. Don't assume anything will be in scope.
 
 #[allow(unused_imports)]
 // enjoy briefer doc comments
-use crate::{notcurses_render, NcDirect, NcError, NcResult, Notcurses, NCRESULT_ERR, NCRESULT_OK};
+use crate::{NcDirect, NcError, NcResult, Notcurses, NCRESULT_ERR, NCRESULT_OK};
 
 // Sleep, Render & Flush Macros ------------------------------------------------
 
@@ -31,7 +32,7 @@ macro_rules! sleep {
     };
 }
 
-/// Notcurses.[render()][Notcurses#method.render]? plus [sleep]!(`sleep_args`).
+/// Notcurses.[render][Notcurses#method.render]\(`nc`\)? plus [sleep]!(`sleep_args`).
 ///
 /// Renders the `$nc` [Notcurses] object and, if there's no error,
 /// calls the sleep macro with the rest of the arguments.
@@ -49,7 +50,7 @@ macro_rules! rsleep {
     };
 }
 
-/// NcDirect.[flush()][NcDirect#method.flush]? plus [sleep]!(`sleep_args`).
+/// NcDirect.[flush][NcDirect#method.flush]\(`ncd`\)? plus [sleep]!(`sleep_args`).
 ///
 /// Flushes the `$ncd` [NcDirect] object and, if there's no error,
 /// calls the sleep macro with the rest of the arguments.