次へ: コメントの書き方のヒント, 前へ: ドキュメント文字列のヒント, 上へ: ヒントと規約   [目次][索引]

D.7 ドキュメントグループ向けのヒント ¶

Emacs 28から利用可能になったドキュメントグループは、さまざまな分類に基づいてLispパッケージの関数を文書化するのに有用です（ドキュメントグループを参照）。本節では、異なるバージョンのEmacsを利用するユーザーが等しくこれらのグループを活用できるよう、Lispパッケージ内でドキュメントグループを定義する方法についていくつかのヒントを紹介します。

• 異なるEmacsバージョン間で独自のLispパッケージのドキュメントグループを定義するには、以下のようなボイラープレートテンプレートを使用することで、エラーなくパッケージをコンパイル・ロードさせることができます。

  ;;; well-doc.el --- a well-documented package -*- lexical-binding: t; -*-
  
  ... package header and contents ...
  

  ;; Explicitly require shortdoc for Emacs 28, which does not have an
  ;; autoload for macro `define-short-documentation-group'.  And for
  ;; Emacs 30, so that we can redefine `shortdoc--check' later.
  (require 'shortdoc nil t)
  
  (eval-when-compile
  
    ;; Default macro `define-short-documentation-group' for Emacs 27
    ;; and older, which do not have the shortdoc feature at all.
    (unless (fboundp 'define-short-documentation-group)
      (defmacro define-short-documentation-group (&rest _)))
  
    ;; Disable too rigid shortdoc checks for Emacs 30, which let it
    ;; error out on newer shortdoc keywords.
    (when (eq emacs-major-version 30)
      (fset 'shortdoc--check #'ignore)))
  

  (define-short-documentation-group well-doc
    ...)
  
  ;;; well-doc.el ends here
  

  上述の Emacs バージョンの一部をサポートしない場合は、テンプレートから該当する形式を省略しても問題ありません。Emacs 31 以降のみをサポートする場合は、上記のいずれも不要であり、define-short-documentation-group を使用すれば十分です。

• 新しいバージョンのEmacsでは、ドキュメントグループに関する新機能やキーワードが導入される場合があります。ただし、これらの機能やキーワードによって、古いバージョンのEmacsにおけるドキュメントグループの表示が崩れることはありません。例えば、将来のEmacsバージョンで利用可能になる仮想的なグループキーワード :super-pretty-print を、Lispパッケージ well-doc.el 内で次のように使用しているとします。

  (define-short-documentation-group well-doc
    (well-doc-foo
     :eval (well-doc-foo)
     :super-pretty-print t))
  

  その将来のEmacsバージョンでは、関数 well-doc-foo の例が極めて美しく整形表示されることになるとされています。旧バージョンのEmacsでは、キーワード :super-pretty-print を黙って無視し、通常の表示ルールに従って例を表示します。