Document defaults to with xxx methods

[AshAnand34]

Pull Request Template

Checklist

• Confirmed that cargo run-checks command has been executed.
• Made sure the book is up to date with changes in this PR.

Tip

Want more detailed macro error diagnostics? This is especially useful for debugging tensor-related tests:

RUSTC_BOOTSTRAP=1 RUSTFLAGS="-Zmacro-backtrace" cargo run-checks

Related Issues/PRs

#2982

Changes

The Config derive macro was missing automatic documentation generation for config structs. This meant that:

1. Field documentation wasn't being propagated to the generated new function
2. Builder methods lacked proper documentation about their purpose and default values
3. Users had to manually document these generated methods, leading to potential inconsistencies.

I added automatic documentation generation to the Config derive macro that:

1. Propagates field documentation to the new function, creating a comprehensive list of all fields with their descriptions
2. Generates documentation for builder methods, including:
   • Purpose of the method
   • Default values for fields with defaults
   • Clear indication of optional fields
3. Handles both required fields, optional fields, and fields with default values appropriately

Testing

Unit tests in burn-core/tests/test_derive_config.rs:

• test_config_documentation() verifies that:
  • Documentation is properly generated for required fields
  • Documentation is properly generated for optional fields
  • Documentation is properly generated for fields with default values
  • Default values are correctly displayed in the documentation

[laggui]

Looks like there are some issues with the modified config derive (see CI).

[laggui]

The generated new method seems to be invalid.

 crates/burn-core/src/nn/conv/conv2d.rs:17:10:
  called `Result::unwrap()` on an `Err` value: Error("expected value", line: 1, column: 1)

Seems to originate from the serde_json::from_str(#value_str).unwrap(). The values are not captured properly it seems.

This also seems to be reflected in the docstrings, e.g.

Create a new instance of the config.

Fields:

#_name: #_doc
#_name: #_doc
#_name: #_doc Default: #_value_str
#_name: #_doc Default: #_value_str
#_name: #_doc Default: #_value_str
#_name: #_doc Default: #_value_str
#_name: #_doc Default: #value
#_name: #_doc Default: #_value_str

[laggui]

While it now seems to at least compile, the docstring still remains incorrect it.

Have you tested it on your end to see if it correctly parses and displays the fields?

I think we can keep this simple without the need for serde_json. Perhaps just check if field.doc() contains a docstring and work from there.

[codecov]

Codecov Report

Attention: Patch coverage is 92.08333% with 19 lines in your changes missing coverage. Please review.

Project coverage is 82.14%. Comparing base (3275d1a) to head (16c39c3).

Files with missing lines	Patch %	Lines
crates/burn-derive/src/config/analyzer_struct.rs	90.05%	18 Missing ⚠️
crates/burn-core/tests/test_derive_config.rs	98.30%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3151      +/-   ##
==========================================
- Coverage   82.14%   82.14%   -0.01%     
==========================================
  Files         959      959              
  Lines      121990   122167     +177     
==========================================
+ Hits       100213   100356     +143     
- Misses      21777    21811      +34     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[laggui]

This additional dependency is not desired for the config derive usage. It also breaks no-std usage.

[laggui]

While it now seems to at least compile, the docstring still remains incorrect it.

Have you tested it on your end to see if it correctly parses and displays the fields?

I think we can keep this simple without the need for serde_json. Perhaps just check if field.doc() contains a docstring and work from there.