O Apêndice D.7 do Emacs Lisp Reference Manual menciona algumas dicas de comentários:
- Ponto-e-vírgula simples (
;
) deve ser usado para comentários embutidos. - Ponto-e-vírgula duplo (
;;
) deve ser usado para comentários de linha. - Ponto-e-vírgula triplo (
;;;
) deve ser usado para "comentários que devem ser considerados um cabeçalho pelo modo secundário de estrutura de tópicos". - Ponto-e-vírgula quádruplo (
;;;;
) deve ser usado para os títulos das seções principais de um programa.
Os casos de uso de ponto e vírgula único e duplo são claros, mas não parece haver uma definição precisa entre ponto e vírgula triplo e quádruplo.
Em particular, a documentação padrão para pacotes Emacs fornecida por auto-insert
usa ponto e vírgula tripla, nunca quadricula ponto e vírgula, mesmo para os títulos de mais alto nível, como nome de arquivo e seções principais. Veja o exemplo abaixo:
;;; test.el --- A test file. -*- lexical-binding: t; -*-
;; Copyright (C) 2016
;; Author: John Smith
;; Keywords:
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
;;; Commentary:
;;
;;; Code:
(provide 'test)
;;; test.el ends here
Quais são as melhores práticas para ponto e vírgula triplo e quádruplo?
Atualizar
Graças à resposta de Stefan , arquivei um relatório de bug e fiz a seguinte sugestão:
Sugiro que a descrição de três pontos e vírgulas seja alterada para:
Comments that start with three semicolons, ‘;;;’, are considered top-level headings by Outline minor mode. Four or more semicolons can be used as subheadings in hierarchical fashion. E.g. ;;; Main heading ;;;; Sub heading ;;;;; Sub sub heading ;;;; Another sub heading ;;; Next main heading These comments should be used to break Emacs Lisp code into sections.
Um link para "Modo secundário de estrutura de tópicos" no manual do Emacs seria útil: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html
A seção para quatro ponto e vírgula pode ser elidida.
grep -r '^;;;; ' lisp
) inspiração.