[rust] export widgets from its own separate module

- update & fix docs.

rust/src/lib.rs

@@ -33,7 +33,7 @@
 //!
 //! Although you still have to manually call the `stop()` method for [`Nc`] and
 //! [`NcDirect`] objects, and the `destroy()` method for the rest of types that
-//! allocate, (like [`NcPlane`], [`NcMenu`]…) at the end of their scope, since
+//! allocate, (like [`NcPlane`], [`NcVisual`]…) at the end of their scope, since
 //! the Drop trait is not implemented for any wrapping type in libnotcurses-sys.
 //!
 //! But they do implement methods and use [`NcResult`] as the return type,
@@ -133,7 +133,7 @@ mod resizecb;
 mod stats;
 mod time;
 mod visual;
-mod widgets;
+pub mod widgets;
 
 pub use crate::input::*;
 pub use capabilities::*;
@@ -155,4 +155,3 @@ pub use resizecb::*;
 pub use stats::*;
 pub use time::*;
 pub use visual::*;
-pub use widgets::*;

rust/src/widgets/menu/methods/menu.rs

@@ -1,24 +1,28 @@
 use core::ptr::null_mut;
 
 use crate::{
-    cstring, error, error_ref_mut, error_str, ncmenu_create, NcInput, NcMenu, NcMenuOptions,
+    cstring, error, error_ref_mut, error_str, ncmenu_create,
-    NcPlane, NcResult,
+    widgets::{NcMenu, NcMenuOptions},
+    NcInput, NcPlane, NcResult,
 };
 
+#[allow(unused_imports)]
+use crate::widgets::{NcMenuItem, NcMenuSection};
+
 /// # `NcMenu` constructors & destructors
 impl NcMenu {
-    /// Creates an [NcMenu] with the specified options.
+    /// Creates an [`NcMenu`] with the specified options.
     ///
-    /// Menus are currently bound to an overall [Notcurses][crate::Notcurses]
+    /// Menus are currently bound to an overall [`Notcurses`][crate::Notcurses]
     /// object (as opposed to a particular plane), and are implemented as
-    /// [NcPlane]s kept atop other NcPlanes.
+    /// [`NcPlane`]s kept atop other NcPlanes.
     ///
     /// *C style function: [ncmenu_create()][crate::ncmenu_create].*
     pub fn new<'a>(plane: &mut NcPlane, options: NcMenuOptions) -> NcResult<&'a mut Self> {
         error_ref_mut![unsafe { ncmenu_create(plane, &options) }, "Creating NcMenu"]
     }
 
-    /// Destroys an NcMenu created with [new()][NcMenu#method.new].
+    /// Destroys an `NcMenu` created with [`new`][NcMenu#method.new].
     ///
     /// *C style function: [ncmenu_destroy()][crate::ncmenu_destroy].*
     pub fn destroy(&mut self) -> NcResult<()> {
@@ -28,7 +32,7 @@ impl NcMenu {
 
 /// # `NcMenu` methods
 impl NcMenu {
-    /// Disables or enables an [NcMenuItem][crate::NcMenuItem].
+    /// Disables or enables an [`NcMenuItem`].
     ///
     /// *C style function: [ncmenu_item_set_status()][crate::ncmenu_item_set_status].*
     pub fn item_set_status(&mut self, section: &str, item: &str, enabled: bool) -> NcResult<()> {
@@ -43,7 +47,7 @@ impl NcMenu {
         ]
     }
 
-    /// Returns the [NcMenuItem][crate::NcMenuItem] description
+    /// Returns the [`NcMenuItem`] description
     /// corresponding to the mouse `click`.
     ///
     /// The NcMenuItem must be on an actively unrolled section, and the click
@@ -88,7 +92,7 @@ impl NcMenu {
         error![unsafe { crate::ncmenu_nextsection(self) }]
     }
 
-    /// Offers the `input` to this NcMenu.
+    /// Offers the `input` to this `NcMenu`.
     ///
     /// If it's relevant, this function returns true,
     /// and the input ought not be processed further.
@@ -107,7 +111,7 @@ impl NcMenu {
         unsafe { crate::ncmenu_offer_input(self, &input) }
     }
 
-    /// Returns the [NcPlane] backing this NcMenu.
+    /// Returns the [`NcPlane`] backing this `NcMenu`.
     ///
     /// *C style function: [ncmenu_plane()][crate::ncmenu_plane].*
     pub fn plane(&mut self) -> NcResult<&NcPlane> {
@@ -135,8 +139,8 @@ impl NcMenu {
         error![unsafe { crate::ncmenu_prevsection(self) }]
     }
 
-    /// Rolls up any unrolled [NcMenuSection][crate::NcMenuSection],
+    /// Rolls up any unrolled [`NcMenuSection`]
-    /// and hides this NcMenu if using hiding.
+    /// and hides this `NcMenu` if using hiding.
     ///
     /// *C style function: [ncmenu_rollup()][crate::ncmenu_rollup].*
     pub fn rollup(&mut self) -> NcResult<()> {
@@ -164,9 +168,9 @@ impl NcMenu {
         }
     }
 
-    /// Unrolls the specified [NcMenuSection][crate::NcMenuSection],
+    /// Unrolls the specified [`NcMenuSection`],
-    /// making the menu visible if it was invisible,
+    /// making the menu visible if it was invisible
-    /// and rolling up any NcMenuSection that is already unrolled.
+    /// and rolling up any `NcMenuSection` that is already unrolled.
     ///
     /// *C style function: [ncmenu_unroll()][crate::ncmenu_unroll].*
     pub fn unroll(&mut self, sectionindex: u32) -> NcResult<()> {

rust/src/widgets/menu/methods/mod.rs

@@ -1,8 +1,11 @@
 //! `NcMenu*` methods and associated functions.
 
+use super::{NcMenuItem, NcMenuSection};
+use crate::{cstring_mut, NcInput};
 use core::ptr::null_mut;
 
-use crate::{cstring_mut, NcInput, NcMenuItem, NcMenuSection};
+#[allow(unused_imports)]
+use crate::widgets::NcMenu;
 
 mod menu;
 mod options;
@@ -12,7 +15,7 @@ pub use options::*;
 
 /// # `NcMenuItem` Constructors
 impl NcMenuItem {
-    /// New NcMenuItem for [NcMenu][crate::NcMenu].
+    /// New NcMenuItem for [`NcMenu`].
     pub fn new(desc: &str, shortcut: NcInput) -> Self {
         Self {
             // utf-8 menu item, NULL for horizontal separator
@@ -23,7 +26,7 @@ impl NcMenuItem {
         }
     }
 
-    /// New empty NcMenuItem for [NcMenu][crate::NcMenu].
+    /// New empty NcMenuItem for [`NcMenu`].
     pub fn new_empty() -> Self {
         Self {
             desc: null_mut(),
@@ -36,7 +39,7 @@ impl NcMenuItem {
 ///
 // Must contain at least 1 NcMenuItem.
 impl NcMenuSection {
-    /// New NcMenuSection for [NcMenu][crate::NcMenu].
+    /// New NcMenuSection for [`NcMenu`].
     pub fn new(name: &str, items: &mut [NcMenuItem], shortcut: NcInput) -> Self {
         Self {
             // utf-8 name string
@@ -53,7 +56,7 @@ impl NcMenuSection {
         }
     }
 
-    /// New NcMenuSection separator for [NcMenu][crate::NcMenu].
+    /// New NcMenuSection separator for [`NcMenu`].
     ///
     pub fn new_separator() -> Self {
         Self {

rust/src/widgets/menu/methods/options.rs

@@ -1,17 +1,23 @@
-use crate::{NcChannels, NcMenuOptions, NcMenuSection};
+use crate::{
+    widgets::{NcMenuOptions, NcMenuSection},
+    NcChannels,
+};
+
+#[allow(unused_imports)]
+use crate::widgets::NcMenu;
 
 /// # `NcMenuOptions` constructors
 impl NcMenuOptions {
-    /// New NcMenuOptions for [NcMenu][crate::NcMenu].
+    /// New NcMenuOptions for [`NcMenu`].
     ///
-    /// `sections` must contain at least 1 [NcMenuSection].
+    /// `sections` must contain at least 1 [`NcMenuSection`].
     pub fn new(sections: &mut [NcMenuSection]) -> Self {
         Self::with_all_args(sections, 0, 0, 0)
     }
 
-    /// New NcMenuOptions for [NcMenu][crate::NcMenu], with all args.
+    /// New NcMenuOptions for [`NcMenu`], with all args.
     ///
-    /// `sections` must contain at least 1 [NcMenuSection].
+    /// `sections` must contain at least 1 [`NcMenuSection`].
     pub fn with_all_args(
         sections: &mut [NcMenuSection],
         style_header: NcChannels,

rust/src/widgets/mod.rs

@@ -1,4 +1,4 @@
-//! Widgets
+//! All the notcurses widgets.
 
 mod menu;
 mod multiselector;

rust/src/widgets/progbar/methods.rs

@@ -1,6 +1,7 @@
 //! `NcProgBar` & `NcProgBarOptions` methods and associated functions.
 
-use crate::{error, NcPlane, NcProgBar, NcProgBarOptions, NcResult};
+use super::{NcProgBar, NcProgBarOptions};
+use crate::{error, NcPlane, NcResult};
 
 /// # `NcProgBarOptions` Methods
 impl NcProgBarOptions {

rust/src/widgets/reader/methods.rs

@@ -1,6 +1,7 @@
 //! `NcReader*` methods and associated functions.
 
-use crate::{error_ref_mut, ncreader_create, NcPlane, NcReader, NcReaderOptions, NcResult};
+use super::{NcReader, NcReaderOptions};
+use crate::{error_ref_mut, ncreader_create, NcPlane, NcResult};
 
 /// # `NcReaderOptions` Constructors
 impl NcReaderOptions {

rust/src/widgets/tree/methods/mod.rs

@@ -9,7 +9,7 @@ pub use tree::*;
 use core::ptr::null_mut;
 use std::ffi::{c_void, CString};
 
-use crate::NcTreeItem;
+use super::NcTreeItem;
 
 /// # `NcTreeItem` constructor
 impl NcTreeItem {

rust/src/widgets/tree/methods/options.rs

@@ -1,13 +1,19 @@
-use crate::{NcDim, NcTreeItem, NcTreeItemCbUnsafe, NcTreeOptions};
+use crate::{
+    widgets::{NcTreeItem, NcTreeItemCbUnsafe, NcTreeOptions},
+    NcDim,
+};
+
+#[allow(unused_imports)]
+use crate::widgets::NcTree;
 
 /// # `NcTreeOptions` constructors
 impl NcTreeOptions {
-    /// New NcTreeOptions for [NcTree][crate::NcTree].
+    /// New NcTreeOptions for [`NcTree`].
     pub fn new(items: &[NcTreeItem], indentcols: NcDim) -> Self {
         Self::with_all_args(items, items.len(), None, indentcols, 0)
     }
 
-    /// New NcTreeOptions for [NcTree][crate::NcTree], with all args.
+    /// New NcTreeOptions for [`NcTree`], with all args.
     pub fn with_all_args(
         // top-level nctree_item array
         items: &[NcTreeItem],

rust/src/widgets/tree/methods/tree.rs

@@ -1,6 +1,7 @@
 use crate::{
-    error, error_ref_mut, nctree_create, NcError, NcInput, NcPlane, NcResult, NcTree, NcTreeItem,
+    error, error_ref_mut, nctree_create,
-    NcTreeOptions, NCRESULT_ERR,
+    widgets::{NcTree, NcTreeItem, NcTreeOptions},
+    NcError, NcInput, NcPlane, NcResult, NCRESULT_ERR,
 };
 
 /// # `NcTree` constructors & destructors