В Приложении 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
Раздел для четырех точек с запятой может быть исключен.
grep -r '^;;;; ' lisp
) для вдохновения.Ответы:
На самом деле, 3 и более точки с запятой означают заголовки, причем чем больше точек с запятой вы ставите, тем глубже вложение заголовка. Так должно выглядеть
источник
emacs-lisp-mode
настраиваетoutline-minor-mode
. Я предлагаю вам сообщить об этом как об ошибке документации (я думаю, что документ более неясен, чем неправильный, но конечный результат тот же).git://git.sv.gnu.org/emacs.git
и затем отправить патч через негоM-x report-emacs-bug
.