Convenções de comentários do Emacs Lisp

17

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-insertusa 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.

Tianxiang Xiong
fonte
Procure nas fontes do Emacs ( grep -r '^;;;; ' lisp) inspiração.
sds
@sds que exibe alguns aplicativos não padrão de ;;;; nas fontes canônicas;)
Tyler
Foi isso o que eu quis dizer - esta recomendação de 4 ponto e vírgula não pode ser levada muito a sério, OTOH, é preciso também observar o registro de data e hora do arquivo - essas coisas não padrão podem ser obsoletas.
Sd

Respostas:

13

Na verdade, 3 e mais pontos e vírgulas representam títulos, onde quanto mais pontos e vírgulas você colocar, mais profundo será o aninhamento do título. Então deve parecer

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Stefan
fonte
Essa parece ser a prática comum, mas difere das convenções listadas no manual Elisp vinculado na pergunta. Isso é um bug no manual?
Tyler
3
Não é apenas uma questão de prática. É assim que se emacs-lisp-modeconfigura outline-minor-mode. Sugiro que você relate isso como um erro de documentação (acho que o documento não está claro mais do que errado, mas o resultado final é o mesmo).
276 Stefan
Enviei um relatório de bug e ofereci uma sugestão para alterar a documentação para outra coisa. Vejo que posso obter a fonte TexInfo para o manual; existe um repositório no qual eu possa clonar e fazer uma solicitação pull?
Tianxiang Xiong
@TianxiangXiong: Obviamente, o documento faz parte do código-fonte do Emacs, então você pode clonar git://git.sv.gnu.org/emacs.gite enviar um patch via M-x report-emacs-bug.
Stefan
Para referência, aqui estão as convenções Common Lisp . Se o Emacs Lisp realmente usa 3 ponto e vírgula para um título, mas 4 ponto e vírgula para um título menos proeminente, isso parece ilógico e contrário ao que eu vi no CL e em outros ciganos. Talvez seja simplesmente um ajuste melhor para os cabeçalhos no estilo org, então eles também o usaram para o elisp.
Lassi