Im Anhang D.7 des Emacs Lisp-Referenzhandbuchs werden einige Kommentartipps aufgeführt:
- Einzelne Semikolons (
;
) sollten für Inline-Kommentare verwendet werden. - Doppelte Semikolons (
;;
) sollten für Zeilenkommentare verwendet werden. - Dreifache Semikolons (
;;;
) sollten für "Kommentare, die im Nebenmodus" Gliederung "als Überschrift angesehen werden sollten" verwendet werden. - Vierfache Semikolons (
;;;;
) sollten für Überschriften von Hauptabschnitten eines Programms verwendet werden.
Die Anwendungsfälle für einfache und doppelte Semikolons sind klar, aber es scheint keine scharfe Abgrenzung zwischen dreifachen und vierfachen Semikolons zu geben.
Insbesondere verwendet die Standarddokumentation für Emacs-Pakete, die von bereitgestellt wird, auto-insert
dreifache Semikolons, niemals vierfache Semikolons, selbst für die Überschriften der höchsten Ebene wie Dateiname und Hauptabschnitte. Siehe folgendes Beispiel:
;;; 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
Was sind die Best Practices für Dreifach- und Vierfach-Semikolons?
Aktualisieren
Dank Stefans Antwort habe ich einen Fehlerbericht eingereicht und folgenden Vorschlag gemacht:
Ich schlage vor, die Beschreibung für drei Semikolons zu ändern:
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.
Ein Link zum "Nebenmodus" im Emacs-Handbuch wäre nützlich: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html
Der Abschnitt für vier Semikolons kann entfernt werden.
grep -r '^;;;; ' lisp
) nach Inspiration.Antworten:
Tatsächlich stehen 3 und mehr Semikolons für Überschriften, wobei die Verschachtelung der Überschrift umso tiefer ist, je mehr Semikolons Sie setzen. So sollte es aussehen
quelle
emacs-lisp-mode
konfiguriertoutline-minor-mode
. Ich schlage vor, Sie melden dies als Dokumentationsfehler (ich denke, das Dokument ist mehr als falsch, aber das Endergebnis ist das gleiche).git://git.sv.gnu.org/emacs.git
einen Patch klonen und dann über senden könnenM-x report-emacs-bug
.