CSS — Documentation

Code documentation serves two purposes: it makes maintenance easier and it makes us stop and think about our code. If the explanation is too complex, maybe the code is overly complex too. Documenting helps keep our code simple and maintainable.

Commenting

Do not hesitate to be very verbose with your comments, especially when documenting a tricky hack. Use comment blocks to separate the different sections of a partial, and/or to describe what styles the partial covers:

/**
 * Section title
 *
 * Description of section
 */

For single selectors or inline comments, use this syntax:

/* Inline comment */

Make sure to comment any complex selector or rule you write. For example:

/* Select list item 4 to 8, included */
li:nth-child(n+4):nth-child(-n+8) {
	color: red;
}

SassDoc

Use SassDoc to generate documentation for variables, functions, mixins and placeholders. If you’ve used PHPDoc, this should look familiar.

Example:

/// Convert Photoshop tracking value to letter-spacing
///
/// @author Your Name
///
/// @param {Integer} $psvalue - The value should be the same value as in Photoshop, required
///
/// @group helpers
///
/// @example scss - Usage
/// 	.wide-tracking {
///			@include tracking(50);
///		}
///
/// @example css - CSS output
/// 	.wide-tracking {
///			letter-spacing: .05em;
/// 	}
@mixin tracking($psvalue) {
  letter-spacing: $psvalue / 1000 + em;
}

Read more at SassDoc official documentation.