Соглашения об комментариях Emacs Lisp

17

В Приложении D.7 Справочного руководства по Emacs Lisp упоминаются некоторые советы для комментариев:

  • Одиночные точки с запятой ( ;) должны использоваться для встроенных комментариев.
  • Двойные точки с запятой ( ;;) должны использоваться для комментариев в строке.
  • Тройные точки с запятой ( ;;;) должны использоваться для «комментариев, которые следует считать заголовком в режиме Outline minor».
  • Четырехточечные точки с запятой ( ;;;;) должны использоваться для заголовков основных разделов программы.

Варианты использования одинарной и двойной точки с запятой очевидны, но, похоже, нет четкого разграничения между тройной и четырехкратной точкой с запятой.

В частности, стандартная документация для пакетов Emacs, предоставляемых с auto-insertпомощью тройных точек с запятой, никогда не четырехкратных точек с запятой, даже для заголовков самого высокого уровня, таких как имя файла и основные разделы. Смотрите пример ниже:

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

Каковы наилучшие практики для тройной и четвертой точки с запятой?

Обновить

Благодаря ответу Стефана , я подал отчет об ошибке и сделал следующее предложение:

Я предлагаю изменить описание трех точек с запятой на:

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.

Будет полезна ссылка на «Outline minor mode» в руководстве по Emacs: https://www.gnu.org/software/emacs/manual/html_node/emacs/Outline-Mode.html

Раздел для четырех точек с запятой может быть исключен.

Тяньсян Сюн
источник
Посмотрите источники Emacs ( grep -r '^;;;; ' lisp) для вдохновения.
SDS
@sds, который включает несколько нестандартных приложений ;;;; в канонических источниках;)
Тайлер
Это то, что я имел в виду - эту рекомендацию в 4 точки с запятой нельзя воспринимать слишком серьезно, OTOH, нужно также посмотреть на временную метку файла - эти нестандартные вещи могут быть устаревшими.
SDS

Ответы:

13

На самом деле, 3 и более точки с запятой означают заголовки, причем чем больше точек с запятой вы ставите, тем глубже вложение заголовка. Так должно выглядеть

;;; Main heading
;;;; Sub heading
;;;;; Sub sub heading
;;;; Another sub heading
;;; Next main heading
Стефан
источник
Это кажется обычной практикой, но отличается от соглашений, перечисленных в руководстве Elisp, связанном в вопросе. Это ошибка в руководстве?
Тайлер
3
Это не просто вопрос практики. Вот как emacs-lisp-modeнастраивает outline-minor-mode. Я предлагаю вам сообщить об этом как об ошибке документации (я думаю, что документ более неясен, чем неправильный, но конечный результат тот же).
Стефан
Я отправил отчет об ошибке и предложил изменить документацию на что-то другое. Я вижу, что могу получить исходный текст TexInfo для руководства; Есть ли хранилище, которое я могу клонировать и сделать запрос на удаление?
Тяньсян Сюн
@TianxiangXiong: Конечно, документ является частью исходного кода Emacs, поэтому вы можете клонировать git://git.sv.gnu.org/emacs.gitи затем отправить патч через него M-x report-emacs-bug.
Стефан
Для справки вот соглашения Common Lisp . Если Emacs Lisp действительно использует 3 точки с запятой для заголовка, а затем 4 точки с запятой для менее заметного заголовка, это кажется нелогичным и противоречит тому, что я видел в CL и других списках. Может быть, это просто лучше подходит для заголовков в стиле org-режима, так что они использовали его и для elisp.
Ласси