Document custom setter (#236)

derive_builder/src/lib.rs

@@ -152,7 +152,7 @@
 //!
 //! ## Hidden Fields
 //!
-//! You can hide fields by skipping their setters on the builder struct.
+//! You can hide fields by skipping their setters on (and presence in) the builder struct.
 //!
 //! - Opt-out — skip setters via `#[builder(setter(skip))]` on individual fields.
 //! - Opt-in — set `#[builder(setter(skip))]` on the whole struct
@@ -165,7 +165,7 @@
 //! # extern crate derive_builder;
 //! #
 //! #[derive(Builder)]
-//! struct SetterOptOut {
+//! struct HiddenField {
 //!     setter_present: u32,
 //!     #[builder(setter(skip))]
 //!     setter_skipped: u32,
@@ -175,8 +175,36 @@
 //!
 //! Alternatively, you can use the more verbose form:
 //!
-//! - `#[builder(setter(skip = "true"))]`
-//! - `#[builder(setter(skip = "false"))]`
+//! - `#[builder(setter(skip = true))]`
+//! - `#[builder(setter(skip = false))]`
+//!
+//! ## Custom setters (skip autogenerated setters)
+//!
+//! Similarly to `setter(skip)`, you can say that you will provide your own setter methods.
+//! This simply suppresses the generation of the setter, leaveing the field in the builder,
+//! as `Option<T>`.
+//!
+//! ```rust
+//! # #[macro_use]
+//! # extern crate derive_builder;
+//! #
+//! #[derive(Builder)]
+//! struct SetterOptOut {
+//!     #[builder(setter(custom))]
+//!     custom_setter: u32,
+//! }
+//! impl SetterOptOutBuilder {
+//!     fn custom_setter(&mut self, value: u32) {
+//!         self.custom_setter = Some(value);
+//!     }
+//! }
+//! # fn main() {}
+//! ```
+//!
+//! Again, the more verbose form is accepted:
+//!
+//! - `#[builder(setter(custom = true))]`
+//! - `#[builder(setter(custom = false))]`
 //!
 //! ## Setter Visibility
 //!

derive_builder/tests/skip-setter.rs

@@ -27,7 +27,7 @@ struct SetterOptOut {
 #[builder(setter(skip))]
 struct SetterOptIn {
     setter_skipped_by_shorthand_default: u32,
-    #[builder(setter(skip = "false"))]
+    #[builder(setter(skip = false))] // Should be still OK without quotes
     setter_present_by_explicit_opt_in: u32,
     #[builder(setter)]
     setter_present_by_shorthand_opt_in: u32,