Conventions de commentaire Emacs Lisp

17

L' Appendice D.7 du Manuel de référence Emacs Lisp mentionne quelques conseils de commentaires:

  • Les points-virgules simples ( ;) doivent être utilisés pour les commentaires en ligne.
  • Les doubles points-virgules ( ;;) doivent être utilisés pour les commentaires de ligne.
  • Le point-virgule triple ( ;;;) doit être utilisé pour "les commentaires qui doivent être considérés comme un titre par le mode mineur Outline".
  • Des points-virgules quadruples ( ;;;;) doivent être utilisés pour les en-têtes des principales sections d'un programme.

Les cas d'utilisation simple et double point-virgule sont clairs, mais il ne semble pas y avoir de délimitation nette entre les points-virgules triples et quadruples.

En particulier, la documentation standard pour les packages Emacs fournie par auto-insertutilise des points-virgules triples, jamais des points-virgules quadruples, même pour les en-têtes de plus haut niveau comme le nom de fichier et les sections principales. Voir l'exemple ci-dessous:

;;; 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

Quelles sont les meilleures pratiques pour les points-virgules triples et quadruples?

Mise à jour

Grâce à la réponse de Stefan , j'ai déposé un rapport de bug et fait la suggestion suivante:

Je suggère que la description de trois points-virgules soit modifiée comme suit:

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.

Un lien vers "Outline minor mode" dans le manuel Emacs serait utile: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

La section pour quatre points-virgules peut être supprimée.

Tianxiang Xiong
la source
Cherchez l' grep -r '^;;;; ' lispinspiration dans les sources d'Emacs ( ).
sds
@sds qui présente quelques applications non standard de ;;;; dans les sources canoniques;)
Tyler
C'est ce que je voulais dire - cette recommandation de 4 points-virgules ne peut pas être prise trop au sérieux, OTOH, il faut également regarder l'horodatage du fichier - ces choses non standard pourraient être obsolètes.
sds

Réponses:

13

En fait, trois points-virgule et plus représentent des titres, où plus vous mettez de points-virgules, plus l'imbrication du titre est profonde. Il devrait donc ressembler à

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Stefan
la source
Cela semble être la pratique courante, mais diffère des conventions énumérées dans le manuel Elisp lié à la question. Est-ce un bug dans le manuel?
Tyler
3
Ce n'est pas seulement une question de pratique. Voilà comment se emacs-lisp-modeconfigure outline-minor-mode. Je vous suggère de signaler cela comme un bogue de documentation (je pense que le document n'est pas clair plus que faux, mais le résultat final est le même).
Stefan
J'ai envoyé un rapport de bogue et proposé une modification de la documentation pour autre chose. Je vois que je peux obtenir la source TexInfo pour le manuel; Existe-t-il un référentiel sur lequel je peux cloner et faire une demande d'extraction?
Tianxiang Xiong
@TianxiangXiong: Bien sûr, le doc fait partie du code source d'Emacs, vous pouvez donc cloner git://git.sv.gnu.org/emacs.gitpuis envoyer un patch via M-x report-emacs-bug.
Stefan
Pour référence, voici les conventions Common Lisp . Si Emacs Lisp utilise vraiment 3 points-virgules pour un titre mais 4 points-virgules pour un titre moins important, cela semble illogique et contraire à ce que j'ai vu en CL et dans d'autres lisps. Peut-être que c'est tout simplement un meilleur ajustement pour les en-têtes de style org, ils l'ont donc aussi utilisé pour elisp.
Lassi