Виды комментариев в Emacs Lisp

Виды комментариев в Emacs Lisp.

1 Общая информация

• Есть три типа комментариев:

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

• Пример использования всех типов комментариев:

   1;;; My heading
   2;; A function that greets people
   3(defun greet (&optional name)
   4  "My function"
   5  (message
   6   (concat "Hello "
   7           (if name ; check if nil
   8               name
   9             "World"))))
  10
  11(greet)
  12;; This prints Hello World
  13
  14(greet "Gene")
  15;; This prints Hello Gene
  

• Команда M-; (comment-dwim) автоматически создаёт комментарий соответствующего типа или смещает существующий комментарий в нужное место, в зависимости от количества точек с запятой.

• Литература

  • https://www.gnu.org/software/emacs/manual/html_node/elisp/Comment-Tips.html;
  • https://www.gnu.org/software/emacs/manual/html_node/elisp/Comments.html.

2 Соглашения для комментариев

2.1 ;

• Комментарии, начинающиеся с одной точки с запятой ;, должны быть выровнены по одному и тому же столбцу справа от исходного кода.
• Такие комментарии обычно объясняют, как код в этой строке выполняет свою работу:

  1(setq base-version-list                 ; There was a base
  2      (assoc (substring fn 0 start-vn)  ; version to which
  3             file-version-assoc-list))  ; this looks like
  4                                        ; a subversion.
  

2.2 ;;

• Комментарии, начинающиеся с двух точек с запятой ;;, должны быть выровнены по тому же уровню отступа, что и код.
• Такие комментарии обычно описывают назначение следующих строк или состояние программы в этот момент:

  1(prog1 (setq auto-fill-function
  2             …
  3             …
  4  ;; Update mode line.
  5  (force-mode-line-update)))
  

• Также этот тип комментария используется для комментариев вне функций:

  1;; This Lisp code is run in Emacs when it is to operate as
  2;; a server for other processes.
  

• Если у функции нет строки документации, вместо этого она должна иметь комментарий с двумя точками с запятой прямо перед функцией, объясняющий, что делает функция и как ее правильно вызывать.
• Следует объяснить, что означает каждый аргумент и как функция интерпретирует его возможные значения.

2.3 ;;;

• Комментарии, начинающиеся с трех (или более) точек с запятой ;;;, должен начинаться с левого края.
• Используется для комментариев, которые должны считаться заголовком.
• По умолчанию комментарии, начинающиеся как минимум с трех точек с запятой (за которыми следует один пробел и символ, не являющийся пробелом), считаются заголовками разделов, а комментарии, начинающиеся с двух или менее, — нет.
• Три точки с запятой используются для разделов верхнего уровня, четыре для подразделов, пять для подразделов и так далее:

  1;;; backquote.el --- implement the ` Lisp construct...
  2;;; Commentary:...
  3;;; Code:...
  4;;; backquote.el ends here