feat: add attribute for hiding fields and enum variants

CHANGELOG.md

···
-## [0.4.1] - 2026-01-05
+## [0.5.0] - 2026-01-05
+
+### 🚀 Features
+
+- Add attribute for hiding fields and enum variants
 
 ### 🚜 Refactor
 

crates/hierconf-core/src/attrs.rs

···
         ///
         /// Usage: `#[facet(hierconf::type_doc("Custom documentation for this type."))]`
         TypeDoc(&'static str),
+
+        /// Hide a struct field or enum variant from man page generation.
+        ///
+        /// Usage: `#[facet(hierconf::hide)]`
+        Hide,
     }
 }
 
···
     }
 }
 
+#[cfg(feature = "mangen")]
+fn has_attr(attrs: &[FacetAttr], key: &'static str) -> bool {
+    attrs
+        .iter()
+        .any(|attr| attr.ns == Some("hierconf") && attr.key == key)
+}
+
 /// Extract the application name from a facet type's attributes.
 ///
 /// Looks for `#[facet(hierconf::app_name("..."))]` attributes on the struct.
···
 pub fn extract_type_doc(attrs: &[FacetAttr]) -> Result<Option<&'static str>, HierConfError> {
     Ok(get_attr_opt::<&str>(attrs, "type_doc")?.cloned())
 }
+
+/// Check if an item (field or variant) should be hidden from man page generation.
+///
+/// Looks for `#[facet(hierconf::hide)]` attributes.
+/// Returns `true` if the attribute is present, `false` otherwise.
+#[cfg(feature = "mangen")]
+pub fn is_hidden(attrs: &[FacetAttr]) -> bool {
+    has_attr(attrs, "hide")
+}

crates/hierconf-core/src/lib.rs

···
 
 pub use attrs::{Attr as HierConfAttr, extract_app_name};
 #[cfg(feature = "mangen")]
-pub use attrs::{extract_date, extract_synopsis, extract_type_doc, extract_type_name};
+pub use attrs::{extract_date, extract_synopsis, extract_type_doc, extract_type_name, is_hidden};
 pub use error::HierConfError;
 pub use loader::config_paths;
 

crates/hierconf-mangen/src/description/data.rs

···
 //! 2. Rendering: Generate man pages using only these structures
 
 use facet::{Def, Shape, StructKind, Type, UserType};
-use hierconf_core::{HierConfError, extract_type_doc, extract_type_name};
+use hierconf_core::{HierConfError, extract_type_doc, extract_type_name, is_hidden};
 use std::collections::HashMap;
 use std::convert::TryFrom;
 
···
 fn fields_to_struct_fields(fields: &'static [facet::Field]) -> Result<Vec<Field>, HierConfError> {
     fields
         .iter()
+        .filter(|field| !is_hidden(field.attributes))
         .map(|field| {
             let name = field.name.to_string();
             let doc = doc_to_string(field.doc);
···
 fn fields_to_tuple_fields(fields: &'static [facet::Field]) -> Result<Vec<TypeRef>, HierConfError> {
     fields
         .iter()
+        .filter(|field| !is_hidden(field.attributes))
         .map(|field| {
             // Check for type_name override on the field
             if let Some(type_name_override) = extract_type_name(field.attributes)? {
···
                 let variants: Result<Vec<Variant>, HierConfError> = enum_type
                     .variants
                     .iter()
+                    .filter(|variant| !is_hidden(variant.attributes))
                     .map(|variant| {
                         let name = variant.name.to_string();
                         let doc = doc_to_string(variant.doc);

crates/hierconf-mangen/tests/hide_attribute/enum.roff

···
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH HIDETEST 5 2025-01-15 hierconf
+.SH NAME
+hidetest \- configuration file format
+.SH SYNOPSIS
+Configuration documentation.
+.PP
+See \fBDESCRIPTION\fR for configuration parameters and \fBFILES\fR for configuration file locations.
+.SH DESCRIPTION
+The \fIhidetest\fR configuration file uses the TOML format.
+
+Configuration files are checked in order of precedence, and the first file that exists is loaded. See the \fBFILES\fR section for details.
+
+.SS "Configuration structure"
+.TP
+\fBtest_enum\fR (\fITestEnum\fR)
+Enum field.
+
+See the \fBTypes\fR subsection for details on the \fITestEnum\fR type.
+
+.SS Types
+The following types are used in the configuration file:
+
+.TP
+\fBTestEnum\fR
+Test enum with hidden variant.
+
+Variants:
+
+.RS 4
+.IP \(bu 3
+\fBVisible\fR
+.RS 4
+This variant should be visible.
+.RE
+.IP \(bu 3
+\fBAnotherVisible\fR
+.RS 4
+Another visible variant.
+.RE
+.RE
+
+.SH FILES
+Configuration files are checked in the following order of precedence (highest to lowest). The first file that exists is loaded.
+
+.TP
+\fBtests/hidetest/config.toml\fR
+Test\-specific configuration file.
+
+.TP
+\fB/etc/hidetest/config.toml\fR
+System\-wide configuration file.
+
+.TP
+\fB/usr/share/etc/hidetest/config.toml\fR
+Distribution\-provided defaults.

crates/hierconf-mangen/tests/hide_attribute/main.rs

···
+use facet::Facet;
+use hierconf_core as hierconf;
+use hierconf_mangen::generate_man_page;
+
+#[derive(Facet)]
+#[facet(hierconf::app_name("hidetest"))]
+#[facet(hierconf::date("2025-01-15"))]
+struct TestConfig {
+    /// This field should be visible.
+    visible_field: String,
+    /// This field should be hidden.
+    #[facet(hierconf::hide)]
+    hidden_field: String,
+    /// Another visible field.
+    another_visible: u16,
+}
+
+/// Test enum with hidden variant.
+#[derive(Facet)]
+#[repr(C)]
+enum TestEnum {
+    /// This variant should be visible.
+    Visible,
+    /// This variant should be hidden.
+    #[facet(hierconf::hide)]
+    Hidden,
+    /// Another visible variant.
+    AnotherVisible,
+}
+
+#[derive(Facet)]
+#[facet(hierconf::app_name("hidetest"))]
+#[facet(hierconf::date("2025-01-15"))]
+struct ConfigWithEnum {
+    /// Enum field.
+    test_enum: TestEnum,
+}
+
+#[test]
+fn hierconf_mangen_hide_fields() {
+    let man_page = generate_man_page::<TestConfig>().unwrap();
+    let expected = include_str!("struct.roff");
+    assert_eq!(man_page, expected);
+}
+
+#[test]
+fn hierconf_mangen_hide_variants() {
+    let man_page = generate_man_page::<ConfigWithEnum>().unwrap();
+    let expected = include_str!("enum.roff");
+    assert_eq!(man_page, expected);
+}

crates/hierconf-mangen/tests/hide_attribute/struct.roff

···
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.TH HIDETEST 5 2025-01-15 hierconf
+.SH NAME
+hidetest \- configuration file format
+.SH SYNOPSIS
+Configuration documentation.
+.PP
+See \fBDESCRIPTION\fR for configuration parameters and \fBFILES\fR for configuration file locations.
+.SH DESCRIPTION
+The \fIhidetest\fR configuration file uses the TOML format.
+
+Configuration files are checked in order of precedence, and the first file that exists is loaded. See the \fBFILES\fR section for details.
+
+.SS "Configuration structure"
+.TP
+\fBvisible_field\fR (\fIString\fR)
+This field should be visible.
+
+.TP
+\fBanother_visible\fR (\fIu16\fR)
+Another visible field.
+
+.SH FILES
+Configuration files are checked in the following order of precedence (highest to lowest). The first file that exists is loaded.
+
+.TP
+\fBtests/hidetest/config.toml\fR
+Test\-specific configuration file.
+
+.TP
+\fB/etc/hidetest/config.toml\fR
+System\-wide configuration file.
+
+.TP
+\fB/usr/share/etc/hidetest/config.toml\fR
+Distribution\-provided defaults.