Clear field documentation

Write precise, unambiguous documentation that explains what fields and methods represent rather than implementation details. Avoid recursive definitions, ambiguous terms, and focus on the user-facing behavior and purpose.

Key principles:

• Use precise terminology that accurately describes the field’s purpose
• Explain what a field represents, not how it works internally
• Avoid ambiguous words like “available” when “total” is more accurate
• Make documentation self-contained rather than recursive
• Be explicit about what operations do and don’t do

Examples of improvements:

Instead of:

// Value defines how much of a certain device capacity is available.
// If the capacity is consumable, the consumed amount is deducted and cached in memory by the scheduler.

Write:

// Value defines the total amount of this capacity the device has.
// This field reflects the fixed total capacity and does not change.

Instead of:

// container name

Write:

// The name of the container requesting resources.

Instead of recursive definitions:

// Mixins defines the mixins available for devices and counter sets

Write:

// Mixins provides common definitions that can be used for devices and counter sets in the ResourceSlice.

This approach ensures documentation is immediately understandable without requiring knowledge of implementation details or other parts of the system.