El Apéndice D.7 del Manual de referencia de Emacs Lisp menciona algunos consejos de comentarios:
- Los puntos y comas simples (
;
) deben usarse para comentarios en línea. - Se
;;
deben utilizar puntos y comas dobles ( ) para comentarios de línea. - Los puntos y comas triples (
;;;
) se deben utilizar para "comentarios que se deben considerar un encabezado por el modo secundario Esquema". - Los puntos y comas cuádruples (
;;;;
) deben usarse para encabezados de secciones principales de un programa.
Los casos de uso de punto y coma de punto y coma simples son claros, pero no parece haber una delimitación clara entre punto y coma y punto y coma cuádruples.
En particular, la documentación estándar para los paquetes de Emacs proporcionada por auto-insert
utiliza punto y coma triple, nunca punto y coma, incluso para los títulos de más alto nivel, como el nombre de archivo y las secciones principales. Ver ejemplo a continuación:
;;; 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
¿Cuáles son las mejores prácticas para los puntos y comas triples y cuádruples?
Actualizar
Gracias a la respuesta de Stefan , presenté un informe de error e hice la siguiente sugerencia:
Sugiero que la descripción de tres puntos y comas se cambie a:
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.
Sería útil un enlace al "Modo secundario del esquema" en el manual de Emacs: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html
La sección para cuatro puntos y comas se puede elidir.
grep -r '^;;;; ' lisp
) en busca de inspiración.Respuestas:
En realidad, 3 y más puntos y comas representan encabezados, donde más puntos y comas colocas, más profundo es el anidamiento del encabezado. Entonces debería verse como
fuente
emacs-lisp-mode
configuraoutline-minor-mode
. Le sugiero que informe esto como un error de documentación (creo que el documento no está claro más que mal, pero el resultado final es el mismo).git://git.sv.gnu.org/emacs.git
y luego enviar un parche a través deM-x report-emacs-bug
.