Hide most header docs

Author: ratmice

cfgrammar/src/lib/header.rs

@@ -8,7 +8,8 @@ use regex::{Regex, RegexBuilder};
 use std::{error::Error, fmt};
 
 /// An error regarding the `%grmtools` header section.
-/// It could be any of
+///
+/// It could be any of:
 ///
 /// * An error during parsing the section.
 /// * An error resulting from a value in the section having an invalid value.
@@ -76,6 +77,7 @@ impl fmt::Display for HeaderErrorKind {
 /// }
 /// ```
 #[derive(Debug, Eq, PartialEq)]
+#[doc(hidden)]
 pub struct Namespaced {
     pub namespace: Option<(String, Location)>,
     pub member: (String, Location),
@@ -108,6 +110,7 @@ pub struct GrmtoolsSectionParser<'input> {
 /// To be useful across diverse crates this types fields are limited to types derived from `core::` types.
 /// like booleans, numeric types, and string values.
 #[derive(Debug, Eq, PartialEq)]
+#[doc(hidden)]
 pub enum Value {
     Flag(bool, Location),
     Setting(Setting),
@@ -359,7 +362,7 @@ impl<'input> GrmtoolsSectionParser<'input> {
     }
 }
 
-/// This is an alias for `MarkMap`
+/// A data structure representation of the %grmtools section.
 pub type Header = MarkMap<String, (Location, Value)>;
 
 impl TryFrom<YaccKind> for Value {

cfgrammar/src/lib/markmap.rs

@@ -1,24 +1,24 @@
 use std::borrow::Borrow;
 
-/// MarkMap is a key value data structure that uses an API similar to that of
-/// `std::collections::HashMap` and `std::collections::BTreeMap`.
-///
-/// The current implementation is based on a sorted `Vec` is not optimized for
-/// storing large number of items.
-///
-/// On top of the familiar `std::collections` API it has a few additions:
-///
-/// * Marking a key with a condition.
-/// * Marking a key with a merge behavior.
-/// * A merge operator.
-///
-/// The current *conditions* are [`Used`](MarkMap::mark_used) and [`Required`](MarkMap::mark_required).
-///
-/// The available merge behaviors are [`Theirs`](MergeBehavior::Theirs), [`Ours`](MergeBehavior::Ours),
-/// and [`MutuallyExclusive`](MergeBehavior::MutuallyExclusive).
-///
-/// Merge behaviors configure how the merge operator handles cases where both `MarkMaps` being merged
-/// contain a particular key.
+// MarkMap is a key value data structure that uses an API similar to that of
+// `std::collections::HashMap` and `std::collections::BTreeMap`.
+//
+// The current implementation is based on a sorted `Vec` is not optimized for
+// storing large number of items.
+//
+// On top of the familiar `std::collections` API it has a few additions:
+//
+// * Marking a key with a condition.
+// * Marking a key with a merge behavior.
+// * A merge operator.
+//
+// The current *conditions* are [`Used`](MarkMap::mark_used) and [`Required`](MarkMap::mark_required).
+//
+// The available merge behaviors are [`Theirs`](MergeBehavior::Theirs), [`Ours`](MergeBehavior::Ours),
+// and [`MutuallyExclusive`](MergeBehavior::MutuallyExclusive).
+//
+// Merge behaviors configure how the merge operator handles cases where both `MarkMaps` being merged
+// contain a particular key.
 #[derive(Debug, PartialEq, Eq)]
 pub struct MarkMap<K, V> {
     contents: Vec<(K, u16, Option<V>)>,
@@ -27,6 +27,7 @@ pub struct MarkMap<K, V> {
 /// Defines the merge behavior for a single key in the markmap.
 #[repr(u8)]
 #[derive(Clone, Copy)]
+#[doc(hidden)]
 pub enum MergeBehavior {
     /// The value in `self` takes precedence.
     Theirs = 1 << 0,
@@ -40,19 +41,22 @@ pub enum MergeBehavior {
 /// Conflicting values were present while merging, and the
 /// merge behavior did not specify a means to resolve them.
 #[derive(Debug)]
+#[doc(hidden)]
 pub enum MergeError<K, V> {
     // Contains the key which was present in both, and the value which was present in `Theirs`.
     Exclusivity(K, V),
 }
 
 /// A view into a single entry in a `MarkMap`, which may either be vacant or occupied.
+#[doc(hidden)]
 pub enum Entry<'a, K, V> {
     Occupied(OccupiedEntry<'a, K, V>),
     Vacant(VacantEntry<'a, K, V>),
 }
 
 #[repr(u8)]
 #[derive(Clone, Copy)]
+#[doc(hidden)]
 enum Mark {
     // There are some other interesting marks that could be added based on row polymorphic records.
     // Marks such as `Prohibited` could be used to prove disjointedness.
@@ -179,12 +183,14 @@ impl<K: Ord, V> OccupiedEntry<'_, K, V> {
 }
 
 /// A view into an occupied entry in a `MarkMap`. It is part of the `Entry` enum.
+#[doc(hidden)]
 pub struct OccupiedEntry<'a, K, V> {
     pos: usize,
     map: &'a mut MarkMap<K, V>,
 }
 
 /// A view into a vacant entry in a `MarkMap`. It is part of the `Entry` enum.
+#[doc(hidden)]
 pub struct VacantEntry<'a, K, V> {
     pos: Result<usize, usize>,
     key: K,
@@ -199,6 +205,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Inserts a `key` `value` pair.
+    #[doc(hidden)]
     pub fn insert(&mut self, key: K, val: V) -> Option<V> {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(&key));
         match pos {
@@ -225,6 +232,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Marks `key` as used.
+    #[doc(hidden)]
     pub fn mark_used(&mut self, key: &K) {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(key));
         match pos {
@@ -241,6 +249,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Marks `key` as a required value.
+    #[doc(hidden)]
     pub fn mark_required(&mut self, key: &K) {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(key));
         match pos {
@@ -257,6 +266,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Returns whether `key` is required.
+    #[doc(hidden)]
     pub fn is_required(&self, key: &K) -> bool {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(key));
         match pos {
@@ -266,6 +276,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Sets the merge behavior for `key`.
+    #[doc(hidden)]
     pub fn set_merge_behavior(&mut self, key: &K, mb: MergeBehavior) {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(key));
         match pos {
@@ -287,6 +298,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Returns a `Some(value)` associated with `key` if present otherwise `None`.
+    #[doc(hidden)]
     pub fn get<Q>(&self, key: &Q) -> Option<&V>
     where
         K: Borrow<Q>,
@@ -303,6 +315,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Returns true if the `MarkMap` contains `key` otherwise false.
+    #[doc(hidden)]
     pub fn contains_key<Q>(&self, key: &Q) -> bool
     where
         K: Borrow<Q>,
@@ -312,6 +325,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Removes `key` from the `MarkMap` and returns the previous value when present.
+    #[doc(hidden)]
     pub fn remove(&mut self, key: &K) -> Option<V> {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(key));
         match pos {
@@ -321,6 +335,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Returns an `Entry` for `key`.
+    #[doc(hidden)]
     pub fn entry(&mut self, key: K) -> Entry<K, V> {
         let pos = self.contents.binary_search_by(|(k, _, _)| k.cmp(&key));
         match pos {
@@ -353,6 +368,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     ///
     /// For the behavior of exclusive or mark the behavior as also `Mark::Required`, then after merge call `missing()`
     /// to check all required values.
+    #[doc(hidden)]
     pub fn merge_from(&mut self, other: Self) -> Result<(), MergeError<K, Box<V>>> {
         for (their_key, their_mark, their_val) in other.contents {
             let pos = self.contents.binary_search_by(|x| x.0.cmp(&their_key));
@@ -399,6 +415,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Returns whether `key` has been marked as used.
+    #[doc(hidden)]
     pub fn is_used<Q>(&self, key: &Q) -> bool
     where
         K: Borrow<Q>,
@@ -415,6 +432,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
     }
 
     /// Returns a `Vec` containing all the keys that are not marked as used.
+    #[doc(hidden)]
     pub fn unused(&self) -> Vec<K> {
         let mut ret = Vec::new();
         for (k, mark, v) in &self.contents {
@@ -428,6 +446,7 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
 
     /// Returns a `Vec` containing all the keys that are marked as required,
     /// but have values that are not present in the `MarkMap`.
+    #[doc(hidden)]
     pub fn missing(&self) -> Vec<&K> {
         let mut ret = Vec::new();
         for (k, mark, v) in &self.contents {
@@ -441,10 +460,12 @@ impl<K: Ord + Clone, V> MarkMap<K, V> {
 }
 
 /// Iterator over the owned keys and values of a `MarkMap`.
+#[doc(hidden)]
 pub struct MarkMapIter<K, V> {
     map: MarkMap<K, V>,
 }
 
+#[doc(hidden)]
 impl<K, V> Iterator for MarkMapIter<K, V> {
     type Item = (K, V);
 
@@ -459,11 +480,13 @@ impl<K, V> Iterator for MarkMapIter<K, V> {
 }
 
 /// Iterator over references to keys and values of a `MarkMap`.
+#[doc(hidden)]
 pub struct MarkMapIterRef<'a, K, V> {
     pos: usize,
     map: &'a MarkMap<K, V>,
 }
 
+#[doc(hidden)]
 impl<'a, K, V> Iterator for MarkMapIterRef<'a, K, V> {
     type Item = (&'a K, &'a V);
 
@@ -477,6 +500,7 @@ impl<'a, K, V> Iterator for MarkMapIterRef<'a, K, V> {
     }
 }
 
+#[doc(hidden)]
 impl<'a, K, V> IntoIterator for &'a MarkMap<K, V> {
     type Item = (&'a K, &'a V);
     type IntoIter = MarkMapIterRef<'a, K, V>;

cfgrammar/src/lib/mod.rs

@@ -56,10 +56,8 @@ use bincode::{Decode, Encode};
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 
-#[doc(hidden)]
 pub mod header;
 mod idxnewtype;
-#[doc(hidden)]
 pub mod markmap;
 pub mod newlinecache;
 pub mod span;