Add doc comments to web-sys dictionaries/fields

This commit ensures that web-sys generated dictionaries and fields all
have comments like interfaces do, indicating a bare minimum of what's
happening as well as the required features to enable the API.
This commit is contained in:
Alex Crichton 2019-06-03 13:18:11 -07:00
parent 877c31cdc8
commit 117928f0c0
3 changed files with 63 additions and 6 deletions

View File

@ -293,6 +293,8 @@ pub struct Dictionary {
pub name: Ident,
pub fields: Vec<DictionaryField>,
pub ctor: bool,
pub doc_comment: Option<String>,
pub ctor_doc_comment: Option<String>,
}
#[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
@ -302,6 +304,7 @@ pub struct DictionaryField {
pub js_name: String,
pub required: bool,
pub ty: syn::Type,
pub doc_comment: Option<String>,
}
impl Export {

View File

@ -1281,9 +1281,18 @@ impl ToTokens for ast::Dictionary {
.collect::<Vec<_>>();
let required_names2 = required_names;
let required_names3 = required_names;
let doc_comment = match &self.doc_comment {
None => "",
Some(doc_string) => doc_string,
};
let ctor = if self.ctor {
let doc_comment = match &self.ctor_doc_comment {
None => "",
Some(doc_string) => doc_string,
};
quote! {
#[doc = #doc_comment]
pub fn new(#(#required_names: #required_types),*) -> #name {
let mut _ret = #name { obj: ::js_sys::Object::new() };
#(_ret.#required_names2(#required_names3);)*
@ -1299,6 +1308,7 @@ impl ToTokens for ast::Dictionary {
#[derive(Clone, Debug)]
#[repr(transparent)]
#[allow(clippy::all)]
#[doc = #doc_comment]
pub struct #name {
obj: ::js_sys::Object,
}
@ -1414,8 +1424,13 @@ impl ToTokens for ast::DictionaryField {
let rust_name = &self.rust_name;
let js_name = &self.js_name;
let ty = &self.ty;
let doc_comment = match &self.doc_comment {
None => "",
Some(doc_string) => doc_string,
};
(quote! {
#[allow(clippy::all)]
#[doc = #doc_comment]
pub fn #rust_name(&mut self, val: #ty) -> &mut Self {
use wasm_bindgen::JsValue;
let r = ::js_sys::Reflect::set(

View File

@ -26,6 +26,7 @@ use proc_macro2::{Ident, Span};
use quote::{quote, ToTokens};
use std::collections::{BTreeSet, HashSet};
use std::env;
use std::fmt::Display;
use std::fs;
use std::iter::FromIterator;
use wasm_bindgen_backend::ast;
@ -313,12 +314,33 @@ impl<'src> FirstPassRecord<'src> {
if !self.append_dictionary_members(def.identifier.0, &mut fields) {
return;
}
let name = rust_ident(&camel_case_ident(def.identifier.0));
let extra_feature = name.to_string();
for field in fields.iter_mut() {
let mut doc_comment = Some(format!(
"Configure the `{}` field of this object\n",
field.js_name,
));
self.append_required_features_doc(&*field, &mut doc_comment, &[&extra_feature]);
field.doc_comment = doc_comment;
}
program.dictionaries.push(ast::Dictionary {
name: rust_ident(&camel_case_ident(def.identifier.0)),
let mut doc_comment = format!("The `{}` dictionary\n", def.identifier.0);
if let Some(s) = self.required_doc_string(vec![name.clone()]) {
doc_comment.push_str(&s);
}
let mut dict = ast::Dictionary {
name,
fields,
ctor: true,
});
doc_comment: Some(doc_comment),
ctor_doc_comment: None,
};
let mut ctor_doc_comment = Some(format!("Construct a new `{}`\n", def.identifier.0));
self.append_required_features_doc(&dict, &mut ctor_doc_comment, &[&extra_feature]);
dict.ctor_doc_comment = ctor_doc_comment;
program.dictionaries.push(dict);
}
fn append_dictionary_members(
@ -419,6 +441,7 @@ impl<'src> FirstPassRecord<'src> {
rust_name: rust_ident(&snake_case_ident(field.identifier.0)),
js_name: field.identifier.0.to_string(),
ty,
doc_comment: None,
})
}
@ -740,16 +763,29 @@ impl<'src> FirstPassRecord<'src> {
if required.len() == 0 {
return;
}
let list = required
if let Some(extra) = self.required_doc_string(required) {
doc.push_str(&extra);
}
}
fn required_doc_string<T: Display>(
&self,
features: impl IntoIterator<Item = T>,
) -> Option<String> {
let features = features.into_iter().collect::<Vec<_>>();
if features.len() == 0 {
return None;
}
let list = features
.iter()
.map(|ident| format!("`{}`", ident))
.collect::<Vec<_>>()
.join(", ");
doc.push_str(&format!(
Some(format!(
"\n\n*This API requires the following crate features \
to be activated: {}*",
list,
));
))
}
fn append_callback_interface(
@ -771,6 +807,7 @@ impl<'src> FirstPassRecord<'src> {
rust_name: rust_ident(&snake_case_ident(identifier)),
js_name: identifier.to_string(),
ty: idl_type::IdlType::Callback.to_syn_type(pos).unwrap(),
doc_comment: None,
});
}
_ => {
@ -786,6 +823,8 @@ impl<'src> FirstPassRecord<'src> {
name: rust_ident(&camel_case_ident(item.definition.identifier.0)),
fields,
ctor: true,
doc_comment: None,
ctor_doc_comment: None,
});
}
}