Para comentários grandes que documentam seções ou componentes inteiros, nós usamos um DocBlock-esque multilinhas que se ajuste à nossa largura de 80 colunas.
Aqui está um exemplo real de um CSS que estiliza o cabeçalho da página CSS Wizardry
/**
* O cabeçalho de uma página principal pode ter dois estados diferentes
*
* 1) Um cabeçalho regular com nenhum ou extra tratamentos, só contendo a logo
* e a navegação.
* 2) Uma masthead que tem uma largura flúida (ficando fixo após um certo ponto)
* que tem um imagem de fundo larga, e algum texto de suporte.
*
* O cabeçalho de página é extremamente simples, mas a versão masthead tem uma
* dependência levemente confundida com o wrapper que vive dentro dela.
*/Este nível de detalhes deveria ser a norma para todos os códigos não triviais - descrição de estados, permutações, condições e tratamentos.