Skip to content

Commit

Permalink
Add docstring previews to index files (FuelLabs#3848)
Browse files Browse the repository at this point in the history 
Closes FuelLabs#3820 

I've added a limit of 200 characters so that anything longer would be 75
characters with an ellipsis (not pictured):
![Screen Shot 2023-01-20 at 7 16 37
PM](https://user-images.githubusercontent.com/57543709/213831623-27c5ed84-9f4e-4efe-8d2a-1c7789ca4dc0.png)
  • Loading branch information
@eureka-cpu
eureka-cpu authored Jan 23, 2023
1 parent 313f6b6 commit 86c02c2
Show file tree
Hide file tree
Showing 3 changed files with 156 additions and 61 deletions.
73 changes: 58 additions & 15 deletions forc-plugins/forc-doc/src/descriptor.rs
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
//! Determine whether a [Declaration] is documentable.
use crate::{
doc::{Document, ModuleInfo},
render::{attrsmap_to_html_str, trim_fn_body, ContextType, ItemBody, ItemContext, ItemHeader},
render::{trim_fn_body, ContextType, DocStrings, ItemBody, ItemContext, ItemHeader},
};
use anyhow::Result;
use sway_core::{
Expand Down Expand Up @@ -50,8 +50,13 @@ impl Descriptor {
Ok(Descriptor::NonDocumentable)
} else {
let item_name = struct_decl.name;
let attrs_opt = (!struct_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(struct_decl.attributes));
let (attrs_opt, raw_attributes) = match struct_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(struct_decl.attributes.to_html_string()),
Some(struct_decl.attributes.to_raw_string()),
),
};
let context = (!struct_decl.fields.is_empty())
.then_some(ContextType::StructFields(struct_decl.fields));

Expand All @@ -72,6 +77,7 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context },
},
raw_attributes,
}))
}
}
Expand All @@ -81,8 +87,13 @@ impl Descriptor {
Ok(Descriptor::NonDocumentable)
} else {
let item_name = enum_decl.name;
let attrs_opt = (!enum_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(enum_decl.attributes));
let (attrs_opt, raw_attributes) = match enum_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(enum_decl.attributes.to_html_string()),
Some(enum_decl.attributes.to_raw_string()),
),
};
let context = (!enum_decl.variants.is_empty())
.then_some(ContextType::EnumVariants(enum_decl.variants));

Expand All @@ -103,6 +114,7 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context },
},
raw_attributes,
}))
}
}
Expand All @@ -112,8 +124,13 @@ impl Descriptor {
Ok(Descriptor::NonDocumentable)
} else {
let item_name = trait_decl.name;
let attrs_opt = (!trait_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(trait_decl.attributes));
let (attrs_opt, raw_attributes) = match trait_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(trait_decl.attributes.to_html_string()),
Some(trait_decl.attributes.to_raw_string()),
),
};
let context = (!trait_decl.interface_surface.is_empty()).then_some(
ContextType::RequiredMethods(
trait_decl.interface_surface.to_methods(decl_engine),
Expand All @@ -137,14 +154,20 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context },
},
raw_attributes,
}))
}
}
AbiDeclaration(ref decl_id) => {
let abi_decl = decl_engine.get_abi(decl_id.clone(), &decl_id.span())?;
let item_name = abi_decl.name;
let attrs_opt = (!abi_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(abi_decl.attributes));
let (attrs_opt, raw_attributes) = match abi_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(abi_decl.attributes.to_html_string()),
Some(abi_decl.attributes.to_raw_string()),
),
};
let context = (!abi_decl.interface_surface.is_empty()).then_some(
ContextType::RequiredMethods(
abi_decl.interface_surface.to_methods(decl_engine),
Expand All @@ -166,15 +189,21 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context },
},
raw_attributes,
}))
}
StorageDeclaration(ref decl_id) => {
let storage_decl = decl_engine.get_storage(decl_id.clone(), &decl_id.span())?;
let item_name = sway_types::BaseIdent::new_no_trim(
sway_types::span::Span::from_string(CONTRACT_STORAGE.to_string()),
);
let attrs_opt = (!storage_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(storage_decl.attributes));
let (attrs_opt, raw_attributes) = match storage_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(storage_decl.attributes.to_html_string()),
Some(storage_decl.attributes.to_raw_string()),
),
};
let context = (!storage_decl.fields.is_empty())
.then_some(ContextType::StorageFields(storage_decl.fields));

Expand All @@ -195,6 +224,7 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context },
},
raw_attributes,
}))
}
ImplTrait(ref decl_id) => {
Expand All @@ -221,6 +251,7 @@ impl Descriptor {
attrs_opt: None, // no attributes field
item_context: ItemContext { context: None },
},
raw_attributes: None,
}))
}
FunctionDeclaration(ref decl_id) => {
Expand All @@ -229,8 +260,13 @@ impl Descriptor {
Ok(Descriptor::NonDocumentable)
} else {
let item_name = fn_decl.name;
let attrs_opt = (!fn_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(fn_decl.attributes));
let (attrs_opt, raw_attributes) = match fn_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(fn_decl.attributes.to_html_string()),
Some(fn_decl.attributes.to_raw_string()),
),
};

Ok(Descriptor::Documentable(Document {
module_info: module_info.clone(),
Expand All @@ -249,6 +285,7 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context: None },
},
raw_attributes,
}))
}
}
Expand All @@ -258,8 +295,13 @@ impl Descriptor {
Ok(Descriptor::NonDocumentable)
} else {
let item_name = const_decl.name;
let attrs_opt = (!const_decl.attributes.is_empty())
.then(|| attrsmap_to_html_str(const_decl.attributes));
let (attrs_opt, raw_attributes) = match const_decl.attributes.is_empty() {
true => (None, None),
false => (
Some(const_decl.attributes.to_html_string()),
Some(const_decl.attributes.to_raw_string()),
),
};

Ok(Descriptor::Documentable(Document {
module_info: module_info.clone(),
Expand All @@ -278,6 +320,7 @@ impl Descriptor {
attrs_opt,
item_context: ItemContext { context: None },
},
raw_attributes,
}))
}
}
Expand Down
15 changes: 15 additions & 0 deletions forc-plugins/forc-doc/src/doc.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ pub(crate) struct Document {
pub(crate) module_info: ModuleInfo,
pub(crate) item_header: ItemHeader,
pub(crate) item_body: ItemBody,
pub(crate) raw_attributes: Option<String>,
}
impl Document {
/// Creates an HTML file name from the [Document].
Expand All @@ -44,6 +45,20 @@ impl Document {
name: self.item_header.item_name.as_str().to_owned(),
module_info: self.module_info.clone(),
html_filename: self.html_filename(),
preview_opt: self.preview_opt(),
}
}
fn preview_opt(&self) -> Option<String> {
match &self.raw_attributes {
Some(description) => {
if description.len() > 200 {
let (first, _) = description.split_at(75);
Some(format!("{}...", first.trim_end()))
} else {
Some(description.to_string())
}
}
None => None,
}
}
/// Gather [Documentation] from the [TyProgram].
Expand Down
Loading

0 comments on commit 86c02c2

Please sign in to comment.