Add documentation and MDN links for webidl files. Fixes #513 (#581)

crates/webidl/src/lib.rs

@@ -40,7 +40,7 @@ use heck::{ShoutySnakeCase};
 use quote::ToTokens;
 
 use first_pass::{FirstPass, FirstPassRecord};
-use util::{public, webidl_const_ty_to_syn_ty, webidl_const_v_to_backend_const_v, TypePosition, camel_case_ident};
+use util::{public, webidl_const_ty_to_syn_ty, webidl_const_v_to_backend_const_v, TypePosition, camel_case_ident, mdn_doc};
 
 pub use error::{Error, ErrorKind, Result};
 
@@ -272,6 +272,8 @@ impl WebidlParse<()> for webidl::ast::NonPartialInterface {
             return Ok(());
         }
 
+        let doc_comment = Some(format!("The `{}` object\n\n{}", &self.name, mdn_doc(&self.name, None)));
+
         program.imports.push(backend::ast::Import {
             module: None,
             version: None,
@@ -280,6 +282,7 @@ impl WebidlParse<()> for webidl::ast::NonPartialInterface {
                 vis: public(),
                 name: rust_ident(camel_case_ident(&self.name).as_str()),
                 attrs: Vec::new(),
+                doc_comment,
             }),
         });
 
@@ -363,6 +366,7 @@ impl<'a> WebidlParse<&'a webidl::ast::NonPartialInterface> for webidl::ast::Exte
                     kind,
                     structural,
                     throws,
+                    None,
                 )
                 .map(wrap_import_function)
                 .map(|import| program.imports.push(import));

crates/webidl/src/util.rs

@@ -25,6 +25,14 @@ pub fn camel_case_ident(identifier: &str) -> String {
   identifier.replace("HTML", "HTML_").to_camel_case()
 }
 
+// Returns a link to MDN
+pub fn mdn_doc(class: &str, method: Option<&str>) -> String {
+    let mut link = format!("https://developer.mozilla.org/en-US/docs/Web/API/{}", class);
+    if let Some(method) = method {
+        link.push_str(&format!("/{}", method));
+    }
+    format!("[Documentation]({})", link).into()
+}
 
 /// For a webidl const type node, get the corresponding syn type node.
 pub fn webidl_const_ty_to_syn_ty(ty: &webidl::ast::ConstType) -> syn::Type {
@@ -317,6 +325,7 @@ impl<'a> FirstPassRecord<'a> {
         kind: backend::ast::ImportFunctionKind,
         structural: bool,
         catch: bool,
+        doc_comment: Option<String>,
     ) -> Option<backend::ast::ImportFunction>
     where
         I: Iterator<Item = (&'b str, &'b webidl::ast::Type, bool)>,
@@ -355,6 +364,7 @@ impl<'a> FirstPassRecord<'a> {
             structural,
             kind,
             shim,
+            doc_comment,
         })
     }
 
@@ -397,6 +407,7 @@ impl<'a> FirstPassRecord<'a> {
                 }
             }
         };
+        let doc_comment = Some(format!("The `{}()` method\n\n{}", name, mdn_doc(self_name, Some(name))));
 
         self.create_function(
             &name,
@@ -407,6 +418,7 @@ impl<'a> FirstPassRecord<'a> {
             kind,
             false,
             catch,
+            doc_comment,
         )
     }
 
@@ -436,8 +448,9 @@ impl<'a> FirstPassRecord<'a> {
                 kind: backend::ast::OperationKind::Getter(Some(raw_ident(name))),
             }),
         };
+        let doc_comment = Some(format!("The `{}` getter\n\n{}", name, mdn_doc(self_name, Some(name))));
 
-        self.create_function(name, iter::empty(), ret, kind, is_structural, catch)
+        self.create_function(name, iter::empty(), ret, kind, is_structural, catch, doc_comment)
     }
 
     /// Create a wasm-bindgen setter method, if possible.
@@ -458,6 +471,7 @@ impl<'a> FirstPassRecord<'a> {
                 kind: backend::ast::OperationKind::Setter(Some(raw_ident(name))),
             }),
         };
+        let doc_comment = Some(format!("The `{}` setter\n\n{}", name, mdn_doc(self_name, Some(name))));
 
         self.create_function(
             &format!("set_{}", name),
@@ -466,6 +480,7 @@ impl<'a> FirstPassRecord<'a> {
             kind,
             is_structural,
             catch,
+            doc_comment,
         )
     }
 }