Skip to content

Commit

Permalink
Use doc_auto_cfg feature instead of ad-hoc #[doc] comments.
Browse files Browse the repository at this point in the history 
docs.rs uses the nightly compiler, allowing to enable the doc_auto_cfg,
which automatically documents the features required for each documented
item.

Before:
$ du -sh crates/libs/{sys,windows}
32M	crates/libs/sys
178M	crates/libs/windows

After:
$ du -sh crates/libs/{sys,windows}
21M	crates/libs/sys
164M	crates/libs/windows
  • Loading branch information
@glandium
glandium committed Aug 15, 2022
1 parent c55af26 commit 89a2e85
Show file tree
Hide file tree
Showing 918 changed files with 6 additions and 403,541 deletions.
3 changes: 0 additions & 3 deletions crates/libs/bindgen/src/classes.rs
View file
Expand Up @@ -27,7 +27,6 @@ fn gen_class(gen: &Gen, def: TypeDef) -> TokenStream {
let mut method_names = MethodNames::new();

let cfg = gen.reader.type_def_cfg(def, &[]);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

for interface in &interfaces {
Expand Down Expand Up @@ -94,7 +93,6 @@ fn gen_class(gen: &Gen, def: TypeDef) -> TokenStream {
};

let mut tokens = quote! {
#doc
#features
#[repr(transparent)]
pub struct #name(::windows::core::IUnknown);
Expand All @@ -117,7 +115,6 @@ fn gen_class(gen: &Gen, def: TypeDef) -> TokenStream {
tokens
} else {
let mut tokens = quote! {
#doc
#features
pub struct #name;
#features
Expand Down
8 changes: 0 additions & 8 deletions crates/libs/bindgen/src/com_methods.rs
View file
Expand Up @@ -8,7 +8,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let where_clause = gen.where_clause(&signature.params);
let mut cfg = gen.reader.signature_cfg(&signature);
cfg.add_feature(gen.reader.type_def_namespace(def));
let doc = gen.cfg_method_doc(&cfg);
let features = gen.cfg_features(&cfg);

if kind == InterfaceKind::None {
Expand All @@ -30,7 +29,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let where_clause = expand_where_clause(where_clause, quote!(T: ::windows::core::Interface));

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params) -> ::windows::core::Result<T> #where_clause {
let mut result__ = ::core::option::Option::None;
Expand All @@ -45,7 +43,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let where_clause = expand_where_clause(where_clause, quote!(T: ::windows::core::Interface));

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params result__: *mut ::core::option::Option<T>) -> ::windows::core::Result<()> #where_clause {
(::windows::core::Interface::vtable(self)#bases.#vname)(::windows::core::Interface::as_raw(self), #args).ok()
Expand All @@ -60,7 +57,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let return_type_tokens = gen.type_name(&return_type);

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params) -> ::windows::core::Result<#return_type_tokens> #where_clause {
let mut result__ = ::core::mem::MaybeUninit::zeroed();
Expand All @@ -74,7 +70,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let params = gen.win32_params(&signature.params, kind);

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params) -> ::windows::core::Result<()> #where_clause {
(::windows::core::Interface::vtable(self)#bases.#vname)(::windows::core::Interface::as_raw(self), #args).ok()
Expand All @@ -87,7 +82,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let return_type = gen.type_name(&signature.return_type.unwrap());

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params) -> #return_type #where_clause {
let mut result__: #return_type = :: core::mem::zeroed();
Expand All @@ -102,7 +96,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let return_type = gen.return_sig(&signature);

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params) #return_type #where_clause {
(::windows::core::Interface::vtable(self)#bases.#vname)(::windows::core::Interface::as_raw(self), #args)
Expand All @@ -114,7 +107,6 @@ pub fn gen(gen: &Gen, def: TypeDef, kind: InterfaceKind, method: MethodDef, meth
let params = gen.win32_params(&signature.params, kind);

quote! {
#doc
#features
pub unsafe fn #name<#generics>(&self, #params) #where_clause {
(::windows::core::Interface::vtable(self)#bases.#vname)(::windows::core::Interface::as_raw(self), #args)
Expand Down
5 changes: 0 additions & 5 deletions crates/libs/bindgen/src/constants.rs
View file
Expand Up @@ -4,14 +4,12 @@ pub fn gen(gen: &Gen, def: Field) -> TokenStream {
let name = to_ident(gen.reader.field_name(def));
let ty = gen.reader.field_type(def, None).to_const();
let cfg = gen.reader.field_cfg(def);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

if let Some(constant) = gen.reader.field_constant(def) {
if ty == gen.reader.constant_type(constant) {
let value = gen.typed_value(&gen.reader.constant_value(constant));
quote! {
#doc
#features
pub const #name: #value;
}
Expand All @@ -27,13 +25,11 @@ pub fn gen(gen: &Gen, def: Field) -> TokenStream {

if !gen.sys && gen.reader.type_has_replacement(&ty) {
quote! {
#doc
#features
pub const #name: #kind = #kind(#value);
}
} else {
quote! {
#doc
#features
pub const #name: #kind = #value;
}
Expand All @@ -47,7 +43,6 @@ pub fn gen(gen: &Gen, def: Field) -> TokenStream {
let kind = gen.type_default_name(&ty);
let guid = gen.guid(&guid);
quote! {
#doc
#features
pub const #name: #kind = #kind {
fmtid: #guid,
Expand Down
4 changes: 0 additions & 4 deletions crates/libs/bindgen/src/delegates.rs
View file
Expand Up @@ -15,7 +15,6 @@ fn gen_callback(gen: &Gen, def: TypeDef) -> TokenStream {
let signature = gen.reader.method_def_signature(method, &[]);
let return_type = gen.return_sig(&signature);
let cfg = gen.reader.type_def_cfg(def, &[]);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

let params = signature.params.iter().map(|p| {
Expand All @@ -25,7 +24,6 @@ fn gen_callback(gen: &Gen, def: TypeDef) -> TokenStream {
});

quote! {
#doc
#features
pub type #name = ::core::option::Option<unsafe extern "system" fn(#(#params),*) #return_type>;
}
Expand Down Expand Up @@ -60,15 +58,13 @@ fn gen_win_delegate(gen: &Gen, def: TypeDef) -> TokenStream {
let fn_constraint = gen_fn_constraint(gen, def, &signature);

let cfg = gen.reader.type_def_cfg(def, generics);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

let vtbl_signature = gen.vtbl_signature(def, generics, &signature);
let invoke = winrt_methods::gen(gen, def, generics, InterfaceKind::Default, method, &mut MethodNames::new(), &mut MethodNames::new());
let invoke_upcall = winrt_methods::gen_upcall(gen, &signature, quote! { ((*this).invoke) });

let mut tokens = quote! {
#doc
#features
#[repr(transparent)]
pub struct #ident(pub ::windows::core::IUnknown, #phantoms) where #constraints;
Expand Down
5 changes: 0 additions & 5 deletions crates/libs/bindgen/src/enums.rs
View file
Expand Up @@ -7,7 +7,6 @@ pub fn gen(gen: &Gen, def: TypeDef) -> TokenStream {
let underlying_type = gen.type_name(&underlying_type);
let is_scoped = gen.reader.type_def_is_scoped(def);
let cfg = gen.reader.type_def_cfg(def, &[]);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

let mut fields: Vec<(TokenStream, TokenStream)> = gen
Expand Down Expand Up @@ -41,15 +40,13 @@ pub fn gen(gen: &Gen, def: TypeDef) -> TokenStream {

let mut tokens = if is_scoped || !gen.sys {
quote! {
#doc
#features
#[repr(transparent)]
#eq
pub struct #ident(pub #underlying_type);
}
} else {
quote! {
#doc
#features
pub type #ident = #underlying_type;
}
Expand All @@ -71,7 +68,6 @@ pub fn gen(gen: &Gen, def: TypeDef) -> TokenStream {
} else if !gen.sys {
let fields = fields.iter().map(|(field_name, value)| {
quote! {
#doc
#features
pub const #field_name: #ident = #ident(#value);
}
Expand All @@ -83,7 +79,6 @@ pub fn gen(gen: &Gen, def: TypeDef) -> TokenStream {
} else {
let fields = fields.iter().map(|(field_name, value)| {
quote! {
#doc
#features
pub const #field_name: #ident = #value;
}
Expand Down
10 changes: 0 additions & 10 deletions crates/libs/bindgen/src/functions.rs
View file
Expand Up @@ -12,7 +12,6 @@ fn gen_sys_function(gen: &Gen, def: MethodDef) -> TokenStream {
let name = to_ident(gen.reader.method_def_name(def));
let signature = gen.reader.method_def_signature(def, &[]);
let cfg = gen.reader.signature_cfg(&signature);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);
let mut return_type = gen.return_sig(&signature);

Expand All @@ -27,7 +26,6 @@ fn gen_sys_function(gen: &Gen, def: MethodDef) -> TokenStream {
});

quote! {
#doc
#features
pub fn #name(#(#params),*) #return_type;
}
Expand Down Expand Up @@ -62,7 +60,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
};

let cfg = gen.reader.signature_cfg(&signature);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

let kind = gen.reader.signature_kind(&signature);
Expand All @@ -74,7 +71,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let where_clause = expand_where_clause(where_clause, quote!(T: ::windows::core::Interface));

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params) -> ::windows::core::Result<T> #where_clause {
Expand All @@ -94,7 +90,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let where_clause = expand_where_clause(where_clause, quote!(T: ::windows::core::Interface));

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params result__: *mut ::core::option::Option<T>) -> ::windows::core::Result<()> #where_clause {
Expand All @@ -114,7 +109,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let return_type_tokens = gen.type_name(&return_type);

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params) -> ::windows::core::Result<#return_type_tokens> #where_clause {
Expand All @@ -132,7 +126,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let params = gen.win32_params(&signature.params, kind);

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params) -> ::windows::core::Result<()> #where_clause {
Expand All @@ -151,7 +144,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let return_type = gen.type_name(&signature.return_type.unwrap());

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params) -> ::windows::core::Result<#return_type> #where_clause {
Expand All @@ -168,7 +160,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let params = gen.win32_params(&signature.params, kind);

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params) #abi_return_type #where_clause {
Expand All @@ -187,7 +178,6 @@ fn gen_win_function(gen: &Gen, def: MethodDef) -> TokenStream {
let does_not_return = does_not_return(gen, def);

quote! {
#doc
#features
#[inline]
pub unsafe fn #name<#generics>(#params) #does_not_return #where_clause {
Expand Down
43 changes: 0 additions & 43 deletions crates/libs/bindgen/src/gen.rs
View file
Expand Up @@ -341,49 +341,6 @@ impl<'a> Gen<'a> {
//
// Cfg
//

/// Generates doc comments for types, free functions, and constants.
pub(crate) fn cfg_doc(&self, cfg: &Cfg) -> TokenStream {
if !self.doc {
quote! {}
} else {
let mut tokens = format!(r#"`\"{}\"`"#, to_feature(self.namespace));

let mut features = cfg_features(cfg, self.namespace);
if self.windows_extern {
features.retain(|f| !f.starts_with("Windows."));
}
for features in features {
write!(tokens, r#", `\"{}\"`"#, to_feature(features)).unwrap();
}

format!(r#"#[doc = "*Required features: {}*"]"#, tokens).into()
}
}

/// Generates doc comments for member functions (methods) and avoids redundantly declaring the
/// enclosing module feature required by the method's type.
pub(crate) fn cfg_method_doc(&self, cfg: &Cfg) -> TokenStream {
if !self.doc {
quote! {}
} else {
let mut features = cfg_features(cfg, self.namespace);
if features.is_empty() {
quote! {}
} else {
if self.windows_extern {
features.retain(|f| !f.starts_with("Windows."));
}
let mut tokens = String::new();
for features in features {
write!(tokens, r#"`\"{}\"`, "#, to_feature(features)).unwrap();
}
tokens.truncate(tokens.len() - 2);
format!(r#"#[doc = "*Required features: {}*"]"#, tokens).into()
}
}
}

pub(crate) fn cfg_features(&self, cfg: &Cfg) -> TokenStream {
if !self.cfg {
quote! {}
Expand Down
3 changes: 1 addition & 2 deletions crates/libs/bindgen/src/interfaces.rs
View file
Expand Up @@ -37,14 +37,13 @@ fn gen_win_interface(gen: &Gen, def: TypeDef) -> TokenStream {
let phantoms = gen.generic_phantoms(generics);
let constraints = gen.generic_constraints(generics);
let cfg = gen.reader.type_def_cfg(def, &[]);
let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);
let interfaces = gen.reader.type_interfaces(&Type::TypeDef((def, generics.to_vec()))); // TODO: how to avoid copy?

let mut tokens = if is_exclusive {
quote! { #[doc(hidden)] }
} else {
quote! { #doc }
quote! { }
};

tokens.combine(&quote! {
Expand Down
2 changes: 0 additions & 2 deletions crates/libs/bindgen/src/structs.rs
View file
Expand Up @@ -67,12 +67,10 @@ fn gen_struct_with_name(gen: &Gen, def: TypeDef, struct_name: &str, cfg: &Cfg) -
quote! { struct }
};

let doc = gen.cfg_doc(&cfg);
let features = gen.cfg_features(&cfg);

let mut tokens = quote! {
#repr
#doc
#features
pub #struct_or_union #name {#(#fields)*}
};
Expand Down

0 comments on commit 89a2e85

Please sign in to comment.