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 <49202620+Maan2003@users.noreply.github.com>

* Improve code readability

Co-authored-by: Joshua Wade <SecondFlight@users.noreply.github.com>
Co-authored-by: Manmeet Maan <49202620+Maan2003@users.noreply.github.com>

Author: 3 people

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
 

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)*
         }