Conventions de commentaire Emacs Lisp

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.

elisp comment

— Tianxiang Xiong
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

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

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