feat(forc doc): Add impl_trait representation to ItemBody (Fuel…

…Labs#4389) ## Description Adds a trait implementation section to item declarations & fixes CSS for required methods on traits. https://user-images.githubusercontent.com/57543709/236067329-11bb66bd-b7b9-4a46-81d6-520d0e2ece83.mov ## Checklist - [x] I have linked to any relevant issues. Closes FuelLabs#3972 - [x] I have commented my code, particularly in hard-to-understand areas. - [x] I have updated the documentation where relevant (API docs, the reference, and the Sway book). - [x] I have added tests that prove my fix is effective or that my feature works. - [x] I have added (or requested a maintainer to add) the necessary `Breaking*` or `New Feature` labels where relevant. - [x] I have done my best to ensure that my PR adheres to [the Fuel Labs Code Review Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md). - [x] I have requested a review from the relevant team or maintainers. --------- Co-authored-by: Sophie Dankel <[email protected]>
chienkeocl2 · May 4, 2023 · bbe746d · bbe746d
1 parent 990d02f
commit bbe746d
Show file tree

Hide file tree

Showing 12 changed files with 435 additions and 112 deletions.
diff --git a/examples/abi_supertraits/src/main.sw b/examples/abi_supertraits/src/main.sw
@@ -1,5 +1,10 @@
 contract;
 
+struct Foo {}
+impl ABIsupertrait for Foo {
+    fn foo() {}
+}
+
 trait ABIsupertrait {
     fn foo();
 }

diff --git a/forc-plugins/forc-doc/src/assets/ayu.css b/forc-plugins/forc-doc/src/assets/ayu.css
@@ -31,14 +31,12 @@ h1.fqn a {
 h4 {
   border: none;
 }
-.in-band {
-  background-color: #0f1419;
-}
 .docblock code {
   color: #ffb454;
 }
 .code-header {
   color: #e6e1cf;
+  margin-left: 1em;
 }
 .docblock pre > code,
 pre > code {
@@ -189,7 +187,7 @@ nav.main .separator {
   border: 1px solid #5c6773;
 }
 a {
-    color: #c5c5c5;
+  color: #c5c5c5;
 }
 .sidebar h2 a,
 .sidebar h3 a {
@@ -491,4 +489,4 @@ details.dir-entry summary:focus {
 }
 #all-types {
   background-color: #14191f;
-}
+}
diff --git a/forc-plugins/forc-doc/src/assets/swaydoc.css b/forc-plugins/forc-doc/src/assets/swaydoc.css
@@ -152,15 +152,15 @@ h2,
   border-bottom: 1px solid var(--headings-border-bottom-color);
 }
 h3.code-header {
-  font-size: 1.125rem;
+  font-size: 1em;
+  font-weight: 600;
 }
 h4.code-header {
   font-size: 1rem;
 }
 .code-header {
   font-weight: 600;
   border-bottom-style: none;
-  margin: 0;
   padding: 0;
   margin-top: 0.6em;
   margin-bottom: 0.4em;
@@ -249,7 +249,7 @@ ol ol {
   margin-bottom: 0.625em;
 }
 p {
-    margin: 0 0 .6em 0;
+  margin: 0 0 0.6em 0;
 }
 summary {
   outline: none;
@@ -375,13 +375,13 @@ nav.sub {
   padding-left: 24px;
 }
 .sidebar .location {
-    border: 1px solid;
-    font-size: 17px;
-    margin: 30px 10px 20px 10px;
-    text-align: center;
-    word-wrap: break-word;
-    font-weight: inherit;
-    padding: 0;
+  border: 1px solid;
+  font-size: 17px;
+  margin: 30px 10px 20px 10px;
+  text-align: center;
+  word-wrap: break-word;
+  font-weight: inherit;
+  padding: 0;
 }
 .swaydoc.source .sidebar {
   width: 50px;
@@ -639,7 +639,7 @@ h2.location a {
 }
 .content .in-band {
   flex-grow: 1;
-  margin: 0px;
+  margin-top: 0px;
   padding: 0px;
   overflow-wrap: break-word;
   overflow-wrap: anywhere;
@@ -815,6 +815,7 @@ a {
 .in-band:hover > .anchor,
 .impl:hover > .anchor,
 .method.trait-impl:hover > .anchor,
+.method.has-srclink:hover > .anchor,
 .type.trait-impl:hover > .anchor,
 .associatedconstant.trait-impl:hover > .anchor,
 .associatedtype.trait-impl:hover > .anchor {
@@ -824,7 +825,6 @@ a {
 .anchor {
   display: none;
   position: absolute;
-  left: -0.5em;
   background: none !important;
 }
 .anchor.field {
@@ -1865,9 +1865,6 @@ details.swaydoc-toggle[open] > summary.hideme::after {
 .method-toggle[open] {
   margin-bottom: 2em;
 }
-.implementors-toggle[open] {
-  margin-bottom: 2em;
-}
 #trait-implementations-list .method-toggle,
 #synthetic-implementations-list .method-toggle,
 #blanket-implementations-list .method-toggle {
@@ -2002,6 +1999,6 @@ details.swaydoc-toggle[open] > summary.hideme::after {
 .example-links ul {
   margin-bottom: 0;
 }
-#all-types>p {
-    margin: 5px 0;
+#all-types > p {
+  margin: 5px 0;
 }
diff --git a/forc-plugins/forc-doc/src/doc/descriptor.rs b/forc-plugins/forc-doc/src/doc/descriptor.rs
@@ -30,7 +30,7 @@ pub(crate) enum Descriptor {
 }
 
 impl Descriptor {
-    /// Decides whether a [TyDecl] is [Descriptor::Documentable].
+    /// Decides whether a [TyDecl] is [Descriptor::Documentable] and returns a [Document] if so.
     pub(crate) fn from_typed_decl(
         decl_engine: &DeclEngine,
         ty_decl: &ty::TyDecl,
@@ -70,6 +70,7 @@ impl Descriptor {
                             attrs_opt: attrs_opt.clone(),
                             item_context: ItemContext {
                                 context_opt: context,
+                                impl_traits: None,
                             },
                         },
                         raw_attributes: attrs_opt,
@@ -106,6 +107,7 @@ impl Descriptor {
                             attrs_opt: attrs_opt.clone(),
                             item_context: ItemContext {
                                 context_opt: context,
+                                impl_traits: None,
                             },
                         },
                         raw_attributes: attrs_opt,
@@ -153,6 +155,7 @@ impl Descriptor {
                             attrs_opt: attrs_opt.clone(),
                             item_context: ItemContext {
                                 context_opt: context,
+                                impl_traits: None,
                             },
                         },
                         raw_attributes: attrs_opt,
@@ -194,6 +197,7 @@ impl Descriptor {
                         attrs_opt: attrs_opt.clone(),
                         item_context: ItemContext {
                             context_opt: context,
+                            impl_traits: None,
                         },
                     },
                     raw_attributes: attrs_opt,
@@ -228,6 +232,7 @@ impl Descriptor {
                         attrs_opt: attrs_opt.clone(),
                         item_context: ItemContext {
                             context_opt: context,
+                            impl_traits: None,
                         },
                     },
                     raw_attributes: attrs_opt,
@@ -285,7 +290,10 @@ impl Descriptor {
                                 fn_decl.span.as_str(),
                             )),
                             attrs_opt: attrs_opt.clone(),
-                            item_context: ItemContext { context_opt: None },
+                            item_context: ItemContext {
+                                context_opt: None,
+                                impl_traits: None,
+                            },
                         },
                         raw_attributes: attrs_opt,
                     }))
@@ -315,7 +323,10 @@ impl Descriptor {
                                 const_decl.span.as_str(),
                             ),
                             attrs_opt: attrs_opt.clone(),
-                            item_context: ItemContext { context_opt: None },
+                            item_context: ItemContext {
+                                context_opt: None,
+                                impl_traits: None,
+                            },
                         },
                         raw_attributes: attrs_opt,
                     }))

diff --git a/forc-plugins/forc-doc/src/doc/mod.rs b/forc-plugins/forc-doc/src/doc/mod.rs
@@ -6,8 +6,9 @@ use anyhow::Result;
 use std::option::Option;
 use sway_core::{
     decl_engine::DeclEngine,
-    language::ty::{TyAstNodeContent, TyProgram, TySubmodule},
+    language::ty::{TyAstNodeContent, TyDecl, TyImplTrait, TyProgram, TySubmodule},
 };
+use sway_types::Spanned;
 
 mod descriptor;
 pub mod module;
@@ -63,17 +64,22 @@ impl Document {
     ) -> Result<Documentation> {
         // the first module prefix will always be the project name
         let mut docs: Documentation = Default::default();
+        let mut impl_traits: Vec<TyImplTrait> = Vec::new();
         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_engine,
-                    decl,
-                    ModuleInfo::from_ty_module(vec![project_name.to_owned()], None),
-                    document_private_items,
-                )?;
+                if let TyDecl::ImplTrait(impl_trait) = decl {
+                    impl_traits.push(decl_engine.get_impl_trait(&impl_trait.decl_id))
+                } else {
+                    let desc = Descriptor::from_typed_decl(
+                        decl_engine,
+                        decl,
+                        ModuleInfo::from_ty_module(vec![project_name.to_owned()], None),
+                        document_private_items,
+                    )?;
 
-                if let Descriptor::Documentable(doc) = desc {
-                    docs.push(doc)
+                    if let Descriptor::Documentable(doc) = desc {
+                        docs.push(doc)
+                    }
                 }
             }
         }
@@ -89,18 +95,48 @@ impl Document {
                     decl_engine,
                     typed_submodule,
                     &mut docs,
+                    &mut impl_traits,
                     &module_prefix,
                     document_private_items,
                 )?;
             }
         }
 
+        // match for the spans to add the impl_traits to their corresponding doc:
+        // currently this compares the spans as str, but this needs to change
+        // to compare the actual types
+        if !impl_traits.is_empty() {
+            for doc in &mut docs {
+                let mut impl_vec: Vec<TyImplTrait> = Vec::new();
+
+                match doc.item_body.ty_decl {
+                    TyDecl::StructDecl(ref struct_decl) => {
+                        for impl_trait in &impl_traits {
+                            if struct_decl.name.as_str()
+                                == impl_trait.implementing_for.span.as_str()
+                                && struct_decl.name.as_str()
+                                    != impl_trait.trait_name.suffix.span().as_str()
+                            {
+                                impl_vec.push(impl_trait.clone());
+                            }
+                        }
+                    }
+                    _ => continue,
+                }
+
+                if !impl_vec.is_empty() {
+                    doc.item_body.item_context.impl_traits = Some(impl_vec);
+                }
+            }
+        }
+
         Ok(docs)
     }
     fn from_ty_submodule(
         decl_engine: &DeclEngine,
         typed_submodule: &TySubmodule,
         docs: &mut Documentation,
+        impl_traits: &mut Vec<TyImplTrait>,
         module_prefix: &ModuleInfo,
         document_private_items: bool,
     ) -> Result<()> {
@@ -110,23 +146,29 @@ impl Document {
             .push(typed_submodule.mod_name_span.as_str().to_owned());
         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_engine,
-                    decl,
-                    new_submodule_prefix.clone(),
-                    document_private_items,
-                )?;
+                if let TyDecl::ImplTrait(impl_trait) = decl {
+                    impl_traits.push(decl_engine.get_impl_trait(&impl_trait.decl_id))
+                } else {
+                    let desc = Descriptor::from_typed_decl(
+                        decl_engine,
+                        decl,
+                        new_submodule_prefix.clone(),
+                        document_private_items,
+                    )?;
 
-                if let Descriptor::Documentable(doc) = desc {
-                    docs.push(doc)
+                    if let Descriptor::Documentable(doc) = desc {
+                        docs.push(doc)
+                    }
                 }
             }
         }
+
         for (_, submodule) in &typed_submodule.module.submodules {
             Document::from_ty_submodule(
                 decl_engine,
                 submodule,
                 docs,
+                impl_traits,
                 &new_submodule_prefix,
                 document_private_items,
             )?;

diff --git a/forc-plugins/forc-doc/src/render/item/components.rs b/forc-plugins/forc-doc/src/render/item/components.rs
@@ -104,8 +104,9 @@ impl Renderable for ItemBody {
         let decl_ty = ty_decl.doc_name();
         let block_title = ty_decl.as_block_title();
         let sidebar = sidebar.render(render_plan.clone())?;
-        let item_context = (item_context.context_opt.is_some())
-            .then(|| -> Result<Box<dyn RenderBox>> { item_context.render(render_plan.clone()) });
+        let item_context = (item_context.context_opt.is_some()
+            || item_context.impl_traits.is_some())
+        .then(|| -> Result<Box<dyn RenderBox>> { item_context.render(render_plan.clone()) });
         let sway_hjs = module_info.to_html_shorthand_path_string("assets/highlight.js");
         let rendered_module_anchors = module_info.get_anchors()?;