Add missing derived lens documentation (#1696)

* Add missing derived lens documentation * Update CHANGELOG.md * Update link references in CHANGELOG.md * Update derived lens documentation Co-authored-by: Manmeet Maan <[email protected]> * Improve code readability Co-authored-by: Joshua Wade <[email protected]> Co-authored-by: Manmeet Maan <[email protected]>
linebender · Apr 8, 2021 · 2c5d73c · 2c5d73c
1 parent 46c6414
commit 2c5d73c
Show file tree

Hide file tree

Showing 2 changed files with 20 additions and 5 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -30,6 +30,7 @@ You can find its changes [documented below](#070---2021-01-01).
 - `Notification`s can be submitted while handling other `Notification`s ([#1640] by [@cmyr])
 - Added ListIter implementations for OrdMap ([#1641] by [@Lejero])
 - `Padding` can now use `Key<Insets>` ([#1662] by [@cmyr])
+- Added missing documentation on derived lens items ([#1696] by [@lidin])
 - `LifeCycle::DisabledChanged`, `InternalLifeCycle::RouteDisabledChanged` and the `set_disabled()` and `is_disabled()` 
   context-methods to implement disabled ([#1632] by [@xarvic])
 - `LifeCycle::BuildFocusChain` to update the focus-chain ([#1632] by [@xarvic])
@@ -450,6 +451,7 @@ Last release without a changelog :(
 [@SecondFlight]: https://github.com/SecondFlight
 [@lord]: https://github.com/lord
 [@Lejero]: https://github.com/Lejero
+[@lidin]: https://github.com/lidin
 [@xarvic]: https://github.com/xarvic
 [@arthmis]: https://github.com/arthmis
 [@ccqpein]: https://github.com/ccqpein
@@ -672,6 +674,7 @@ Last release without a changelog :(
 [#1677]: https://github.com/linebender/druid/pull/1677
 [#1691]: https://github.com/linebender/druid/pull/1691
 [#1693]: https://github.com/linebender/druid/pull/1693
+[#1696]: https://github.com/linebender/druid/pull/1696
 [#1698]: https://github.com/linebender/druid/pull/1698
 [#1695]: https://github.com/linebender/druid/pull/1695
 

diff --git a/druid-derive/src/lens.rs b/druid-derive/src/lens.rs
@@ -83,18 +83,27 @@ fn derive_struct(input: &syn::DeriveInput) -> Result<proc_macro2::TokenStream, s
     // Define lens types for each field
     let defs = fields.iter().filter(|f| !f.attrs.ignore).map(|f| {
         let field_name = &f.ident.unwrap_named();
-        let docs = format!(
-            "Lens for the field `{}` on [`{1}`](super::{1})",
-            field_name, ty
+        let struct_docs = format!(
+            "Lens for the field `{field}` on [`{ty}`](super::{ty}).",
+            field = field_name,
+            ty = ty,
+        );
+
+        let fn_docs = format!(
+            "Creates a new lens for the field `{field}` on [`{ty}`](super::{ty}). \
+            Use [`{ty}::{field}`](super::{ty}::{field}) instead.",
+            field = field_name,
+            ty = ty,
         );
 
         quote! {
-            #[doc = #docs]
+            #[doc = #struct_docs]
             #[allow(non_camel_case_types)]
             #[derive(Debug, Copy, Clone)]
             pub struct #field_name#lens_ty_generics(#(#phantom_decls),*);
 
             impl #lens_ty_generics #field_name#lens_ty_generics{
+                #[doc = #fn_docs]
                 pub const fn new()->Self{
                     Self(#(#phantom_inits),*)
                 }
@@ -148,12 +157,15 @@ fn derive_struct(input: &syn::DeriveInput) -> Result<proc_macro2::TokenStream, s
         let lens_field_name = f.attrs.lens_name_override.as_ref().unwrap_or(&field_name);
 
         quote! {
-            /// Lens for the corresponding field
+            /// Lens for the corresponding field.
             pub const #lens_field_name: #twizzled_name::#field_name#lens_ty_generics = #twizzled_name::#field_name::new();
         }
     });
 
+    let mod_docs = format!("Derived lenses for [`{}`].", ty);
+
     let expanded = quote! {
+        #[doc = #mod_docs]
         pub mod #twizzled_name {
             #(#defs)*
         }