What is the best way to document classes, options, etc.?

[mrwweb]

Currently all information about optional classes, inline styles, alignments, etc. is included in a comment preceding the block's CSS selectors. Here's the most verbose example:

/*
 * Button
 *
 * Note: Buttons container added in WP5.4
 *
 * Alignments: alignleft, aligncenter, alignright
 * Default Style Variations: is-style-outline
 * Possible Inline Styles: border-radius
 * Color Support: Background, Text
 */

Some questions I would love feedback on:

1. Is this the best possible way to do this?
2. Is any information missing or unclear?
3. What would be a better way?

[kelliwise]

This seems clear but we may need to add more examples for the more complex css rules. One thing that might come in very handy is a table of contents at the top of the file. Example on the front end blocks would be

/* **************

• Table of Contents
• Block Styles
• Colors
• etc
  ***************** */

Just from a maintenance standpoint, it would help find your way to the area where certain selectors are kept and make it easier for people using the code to find what they need.