Add --document-private-items option to forc doc (FuelLabs#3537)

This PR adds the `--document-private-items` tag to `forc doc`, and sorts the items based on visibility while determining whether an item is documentable. Closes FuelLabs#3482
cold-briu · Dec 8, 2022 · 3a80db6 · 3a80db6
1 parent 716b34f
commit 3a80db6
Show file tree

Hide file tree

Showing 4 changed files with 72 additions and 27 deletions.
diff --git a/forc-plugins/forc-doc/src/cli.rs b/forc-plugins/forc-doc/src/cli.rs
@@ -11,6 +11,9 @@ pub struct Command {
     /// file in the current directory or any parent directory.
     #[clap(long)]
     pub manifest_path: Option<String>,
+    /// Include non-public items in the documentation.
+    #[clap(long)]
+    pub document_private_items: bool,
     /// Open the docs in a browser after building them.
     #[clap(long)]
     pub open: bool,

diff --git a/forc-plugins/forc-doc/src/descriptor.rs b/forc-plugins/forc-doc/src/descriptor.rs
@@ -54,29 +54,45 @@ pub(crate) enum Descriptor {
 }
 
 impl Descriptor {
-    pub(crate) fn from_typed_decl(d: &TyDeclaration, module_prefix: Vec<String>) -> Result<Self> {
+    pub(crate) fn from_typed_decl(
+        d: &TyDeclaration,
+        module_prefix: Vec<String>,
+        document_private_items: bool,
+    ) -> Result<Self> {
         use TyDeclaration::*;
         match d {
             StructDeclaration(ref decl_id) => {
                 let struct_decl = de_get_struct(decl_id.clone(), &decl_id.span())?;
-                Ok(Descriptor::Documentable {
-                    module_prefix,
-                    desc_ty: Box::new(DescriptorType::Struct(struct_decl)),
-                })
+                if !document_private_items && struct_decl.visibility.is_private() {
+                    Ok(Descriptor::NonDocumentable)
+                } else {
+                    Ok(Descriptor::Documentable {
+                        module_prefix,
+                        desc_ty: Box::new(DescriptorType::Struct(struct_decl)),
+                    })
+                }
             }
             EnumDeclaration(ref decl_id) => {
                 let enum_decl = de_get_enum(decl_id.clone(), &decl_id.span())?;
-                Ok(Descriptor::Documentable {
-                    module_prefix,
-                    desc_ty: Box::new(DescriptorType::Enum(enum_decl)),
-                })
+                if !document_private_items && enum_decl.visibility.is_private() {
+                    Ok(Descriptor::NonDocumentable)
+                } else {
+                    Ok(Descriptor::Documentable {
+                        module_prefix,
+                        desc_ty: Box::new(DescriptorType::Enum(enum_decl)),
+                    })
+                }
             }
             TraitDeclaration(ref decl_id) => {
                 let trait_decl = de_get_trait(decl_id.clone(), &decl_id.span())?;
-                Ok(Descriptor::Documentable {
-                    module_prefix,
-                    desc_ty: Box::new(DescriptorType::Trait(trait_decl)),
-                })
+                if !document_private_items && trait_decl.visibility.is_private() {
+                    Ok(Descriptor::NonDocumentable)
+                } else {
+                    Ok(Descriptor::Documentable {
+                        module_prefix,
+                        desc_ty: Box::new(DescriptorType::Trait(trait_decl)),
+                    })
+                }
             }
             AbiDeclaration(ref decl_id) => {
                 let abi_decl = de_get_abi(decl_id.clone(), &decl_id.span())?;
@@ -101,17 +117,25 @@ impl Descriptor {
             }
             FunctionDeclaration(ref decl_id) => {
                 let fn_decl = de_get_function(decl_id.clone(), &decl_id.span())?;
-                Ok(Descriptor::Documentable {
-                    module_prefix,
-                    desc_ty: Box::new(DescriptorType::Function(fn_decl)),
-                })
+                if !document_private_items && fn_decl.visibility.is_private() {
+                    Ok(Descriptor::NonDocumentable)
+                } else {
+                    Ok(Descriptor::Documentable {
+                        module_prefix,
+                        desc_ty: Box::new(DescriptorType::Function(fn_decl)),
+                    })
+                }
             }
             ConstantDeclaration(ref decl_id) => {
                 let const_decl = de_get_constant(decl_id.clone(), &decl_id.span())?;
-                Ok(Descriptor::Documentable {
-                    module_prefix,
-                    desc_ty: Box::new(DescriptorType::Const(Box::new(const_decl))),
-                })
+                if !document_private_items && const_decl.visibility.is_private() {
+                    Ok(Descriptor::NonDocumentable)
+                } else {
+                    Ok(Descriptor::Documentable {
+                        module_prefix,
+                        desc_ty: Box::new(DescriptorType::Const(Box::new(const_decl))),
+                    })
+                }
             }
             _ => Ok(Descriptor::NonDocumentable),
         }

diff --git a/forc-plugins/forc-doc/src/doc.rs b/forc-plugins/forc-doc/src/doc.rs
@@ -46,12 +46,13 @@ impl Document {
     pub(crate) fn from_ty_program(
         compilation: &CompileResult<(ParseProgram, Option<TyProgram>)>,
         no_deps: bool,
+        document_private_items: bool,
     ) -> Result<Documentation> {
         let mut docs: Documentation = Default::default();
         if let Some((_, Some(typed_program))) = &compilation.value {
             for ast_node in &typed_program.root.all_nodes {
                 if let TyAstNodeContent::Declaration(ref decl) = ast_node.content {
-                    let desc = Descriptor::from_typed_decl(decl, vec![])?;
+                    let desc = Descriptor::from_typed_decl(decl, vec![], document_private_items)?;
 
                     if let Descriptor::Documentable {
                         module_prefix,
@@ -70,7 +71,12 @@ impl Document {
                 // this is the same process as before but for dependencies
                 for (_, ref typed_submodule) in &typed_program.root.submodules {
                     let module_prefix = vec![];
-                    Document::from_ty_submodule(typed_submodule, &mut docs, &module_prefix)?;
+                    Document::from_ty_submodule(
+                        typed_submodule,
+                        &mut docs,
+                        &module_prefix,
+                        document_private_items,
+                    )?;
                 }
             }
         }
@@ -81,12 +87,17 @@ impl Document {
         typed_submodule: &TySubmodule,
         docs: &mut Documentation,
         module_prefix: &[String],
+        document_private_items: bool,
     ) -> Result<()> {
         let mut new_submodule_prefix = module_prefix.to_owned();
         new_submodule_prefix.push(typed_submodule.library_name.as_str().to_string());
         for ast_node in &typed_submodule.module.all_nodes {
             if let TyAstNodeContent::Declaration(ref decl) = ast_node.content {
-                let desc = Descriptor::from_typed_decl(decl, new_submodule_prefix.clone())?;
+                let desc = Descriptor::from_typed_decl(
+                    decl,
+                    new_submodule_prefix.clone(),
+                    document_private_items,
+                )?;
 
                 if let Descriptor::Documentable {
                     module_prefix,
@@ -102,7 +113,12 @@ impl Document {
         }
         // if there is another submodule we need to go a level deeper
         if let Some((_, submodule)) = typed_submodule.module.submodules.first() {
-            Document::from_ty_submodule(submodule, docs, &new_submodule_prefix)?;
+            Document::from_ty_submodule(
+                submodule,
+                docs,
+                &new_submodule_prefix,
+                document_private_items,
+            )?;
         }
 
         Ok(())

diff --git a/forc-plugins/forc-doc/src/main.rs b/forc-plugins/forc-doc/src/main.rs
@@ -10,7 +10,7 @@ use crate::{
 use anyhow::{bail, Result};
 use clap::Parser;
 use cli::Command;
-use forc_pkg::{self as pkg};
+use forc_pkg as pkg;
 use forc_util::default_output_directory;
 use include_dir::{include_dir, Dir};
 use pkg::manifest::ManifestFile;
@@ -24,6 +24,7 @@ use sway_core::TypeEngine;
 pub fn main() -> Result<()> {
     let Command {
         manifest_path,
+        document_private_items,
         open: open_result,
         offline,
         silent,
@@ -60,7 +61,8 @@ pub fn main() -> Result<()> {
     let compilation = pkg::check(&plan, silent, &type_engine)?
         .pop()
         .expect("there is guaranteed to be at least one elem in the vector");
-    let raw_docs: Documentation = Document::from_ty_program(&compilation, no_deps)?;
+    let raw_docs: Documentation =
+        Document::from_ty_program(&compilation, no_deps, document_private_items)?;
     // render docs to HTML
     let rendered_docs: RenderedDocumentation =
         RenderedDocument::from_raw_docs(&raw_docs, project_name);