chore!: Hide items that are not supposed to appear in the API (#16)

* feat: replace generate_for_docusaurus and generate_for_mdbook functions by buider patterns to provide more options

* feat: add slug option to docusaurus generation

* chore: update docusaurus example with slug option

* fix: slug path

* chore: update docusaurus examples with generated slugs

* fix: slug without options appens / to the module name

* docs: update readme to reflect the changes

* chore: fix lint

* docs: update unresolved items

* refact: hide function unused by the user

src/doc_item.rs

@@ -7,6 +7,7 @@ use crate::{
     },
     ItemsOrder,
 };
+use serde::ser::SerializeStruct;
 
 /// Generic representation of documentation for a specific item. (a function, a custom type, etc.)
 #[derive(Debug, Clone)]
@@ -23,8 +24,6 @@ pub enum DocItem {
     },
 }
 
-use serde::ser::SerializeStruct;
-
 impl serde::Serialize for DocItem {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
@@ -124,7 +123,7 @@ impl Section {
 }
 
 impl DocItem {
-    pub fn new_function(
+    pub(crate) fn new_function(
         metadata: &[FunctionMetadata],
         name: &str,
         options: &Options,
@@ -158,7 +157,7 @@ impl DocItem {
         }
     }
 
-    pub fn new_custom_type(
+    pub(crate) fn new_custom_type(
         metadata: CustomTypesMetadata,
         options: &Options,
     ) -> Result<Option<Self>, AutodocsError> {
@@ -173,12 +172,14 @@ impl DocItem {
         )
     }
 
+    /// Get the index of the item, extracted from the `# rhai-autodocs:index` directive.
     pub fn index(&self) -> usize {
         match self {
             DocItem::CustomType { index, .. } | DocItem::Function { index, .. } => *index,
         }
     }
 
+    /// Get the name of the item.
     pub fn name(&self) -> &str {
         match self {
             DocItem::CustomType { metadata, .. } => metadata.display_name.as_str(),
@@ -187,7 +188,7 @@ impl DocItem {
     }
 
     /// Find the order index of the item by searching for the index pattern.
-    pub fn find_index(doc_comments: &[String]) -> Result<Option<usize>, AutodocsError> {
+    pub(crate) fn find_index(doc_comments: &[String]) -> Result<Option<usize>, AutodocsError> {
         for line in doc_comments {
             if let Some((_, index)) = line.rsplit_once(RHAI_ITEM_INDEX_PATTERN) {
                 return index
@@ -206,7 +207,7 @@ impl DocItem {
 
     /// Format the function doc comments to make them
     /// into readable markdown.
-    pub fn format_comments(doc_comments: &[String]) -> String {
+    pub(crate) fn format_comments(doc_comments: &[String]) -> String {
         let doc_comments = doc_comments.to_vec();
         let removed_extra_tokens = Self::remove_extra_tokens(doc_comments).join("\n");
         let remove_comments = Self::fmt_doc_comments(removed_extra_tokens);
@@ -215,7 +216,7 @@ impl DocItem {
     }
 
     /// Remove crate specific comments, like `rhai-autodocs:index`.
-    pub fn remove_extra_tokens(dc: Vec<String>) -> Vec<String> {
+    pub(crate) fn remove_extra_tokens(dc: Vec<String>) -> Vec<String> {
         dc.into_iter()
             .map(|s| {
                 s.lines()
@@ -227,7 +228,7 @@ impl DocItem {
     }
 
     /// Remove doc comments identifiers.
-    pub fn fmt_doc_comments(dc: String) -> String {
+    pub(crate) fn fmt_doc_comments(dc: String) -> String {
         dc.replace("/// ", "")
             .replace("///", "")
             .replace("/**", "")
@@ -239,7 +240,7 @@ impl DocItem {
     ///       markdown processors might not.
     /// Remove lines of code that starts with the '#' token,
     /// which are removed on rust docs automatically.
-    pub fn remove_test_code(doc_comments: &str) -> String {
+    pub(crate) fn remove_test_code(doc_comments: &str) -> String {
         let mut formatted = vec![];
         let mut in_code_block = false;
         for line in doc_comments.lines() {

src/glossary.rs

@@ -23,7 +23,7 @@ pub struct ModuleGlossary {
 /// # Errors
 /// * Failed to generate function metadata as json.
 /// * Failed to parse module metadata.
-pub fn generate_module_glossary(
+pub(crate) fn generate_module_glossary(
     engine: &rhai::Engine,
     options: &Options,
 ) -> Result<ModuleGlossary, AutodocsError> {

src/lib.rs

@@ -1,14 +1,14 @@
 #![doc = include_str!("../README.md")]
 
-pub mod custom_types;
+mod custom_types;
 pub mod doc_item;
-pub mod function;
+mod function;
 pub mod glossary;
 pub mod module;
 
 pub use glossary::ModuleGlossary;
 pub use module::{
-    options::{export, ItemsOrder, MarkdownProcessor, SectionFormat},
+    options::{ItemsOrder, MarkdownProcessor, SectionFormat},
     ModuleDocumentation,
 };
 use serde_json::json;
@@ -91,14 +91,14 @@ impl MDBookOptions {
 }
 
 pub mod generate {
-    /// Create a new builder to generate documentation for docusaurus from a [`ModuleDocumentation`] object.
+    /// Create a new builder to generate documentation for docusaurus from a [`super::module::ModuleDocumentation`] object.
     pub fn docusaurus() -> super::DocusaurusOptions {
         super::DocusaurusOptions::default()
     }
 
-    /// Create a new builder to generate documentation for mdbook from a [`ModuleDocumentation`] object.
+    /// Create a new builder to generate documentation for mdbook from a [`super::module::ModuleDocumentation`] object.
     pub fn mdbook() -> super::MDBookOptions {
-        super::MDBookOptions::default()
+        super::MDBookOptions
     }
 }
 
@@ -128,3 +128,12 @@ fn generate(
 
     Ok(documentation)
 }
+
+pub mod export {
+    use crate::module::options::Options;
+
+    /// Create new options used to configure docs generation.
+    pub fn options() -> Options {
+        Options::default()
+    }
+}

src/module/options.rs

@@ -26,13 +26,6 @@ pub struct Options {
     pub(crate) include_standard_packages: bool,
 }
 
-pub mod export {
-    /// Create new options used to configure docs generation.
-    pub fn options() -> super::Options {
-        super::Options::default()
-    }
-}
-
 impl Options {
     /// Include the standard package functions and modules documentation
     /// in the generated documentation markdown.
@@ -154,10 +147,6 @@ pub enum SectionFormat {
     Rust,
     /// Display sections using tabs that wraps all underlying
     /// documentation in them.
-    ///
-    /// NOTE: [`SectionFormat::fmt_sections`] is called after [`remove_test_code`],
-    /// so checking for code blocks and `#` line start is not required because it
-    /// was supposed to be removed.
     Tabs,
 }