Clarify state attributes rules for entity

[gjohansson-ST]

Proposed change

Clarify the rules regarding additional state attributes as decided in https://github.com/home-assistant/architecture/discussions/680

Type of change

• [x] Document existing features within Home Assistant
• [ ] Document new or changing features which there is an existing pull request elsewhere
• [ ] Spelling or grammatical corrections, or rewording for improved clarity
• [ ] Changes to the backend of this documentation
• [ ] Removed stale or deprecated documentation

Additional information

• This PR fixes or closes issue: fixes #
• Link to relevant existing code or pull request:

Summary by CodeRabbit

• Documentation
  • Added a new "State attributes" section explaining how entities can expose extra state attributes, expected/unsupported values, handling of None, and guidance on when to use attributes versus separate sensors, with examples. Note: the section currently appears twice in the documentation. (Documentation-only change.)

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Adds documentation to docs/core/entity.md describing extra_state_attributes (state attributes), rules for attribute values and None, guidance on when to use attributes versus separate sensors, and notes that the new section was inserted twice in the Advanced properties area. No code changes.

Changes

Cohort / File(s)	Change summary
Documentation: entity doc docs/core/entity.md	Added new "State attributes" sections describing extra_state_attributes, expected attribute rules (including handling None), guidance on when to use attributes vs separate sensors, and notes about attribute expectations. The content appears duplicated within the Advanced properties area. No functional/code changes.

Sequence Diagram(s)

No sequence diagram — documentation-only changes that do not alter control flow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Potential review focus:

• Confirm whether the duplicated "State attributes" section is intentional; remove one copy if accidental.
• Validate clarity and accuracy of rules for None/unsupported attribute values and the guidance on when to use separate sensors.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title "Clarify state attributes rules for entity" is directly related to the main change in the changeset. According to the raw summary, the PR adds a new "State attributes" section to the documentation describing how entities can provide extra state attributes and the rules governing them. The title accurately and concisely summarizes this primary change, making it clear to reviewers scanning the history that the PR focuses on documenting state attributes guidance. The title is specific and meaningful without unnecessary noise or vague language.
Description Check	✅ Passed	The pull request description includes the two main required sections: "Proposed change" is filled with clear context referencing an architecture discussion, and "Type of change" has the appropriate box checked for documenting existing features. However, the description is missing the entire "Checklist" section that should verify compliance with documentation guidelines and testing, and the "Additional information" section fields are not completed. Despite these structural gaps, the core information necessary to understand the PR's purpose and scope is communicated effectively, meeting the threshold of being mostly complete with the essential content present.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch gj-20241103-1

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[home-assistant[bot]]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks :+1:

Learn more about our pull request process.

[frenck]

@gjohansson-ST Should we move this forward?

[gjohansson-ST]

Yes, I'll try to rewrite from the feedback shortly so we can merge it in.

[gjohansson-ST]

Took a little bit of time but it's now rewritten according to the feedback so far.