02日 9月 2015

emacsのdoxymacsパッケージの使い方

EmacsでDoxygenコメントを全部打つのは面倒なので、Doxygenコメントのテンプレートをショートカットキー経由で出力してくれるdoxymacsの使っています。

使い方を簡単にまとめました。

1 doxymacsとは

ショートカットキー経由でDoxygen用コメントのテンプレートを埋め込むelispパッケージです。

2 インストール方法

Doxymacsのページからdoxymacs-1.8.0.tar.gzを入手します。

Clangだとコンパイルエラーになるので、NetBSDのページからパッチを入手して適用します。

GCCでは不要です。 

$ tar zxf doxymacs-1.8.0.tar.gz
$ cd doxymacs-1.8.0
$ wget http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/devel/doxymacs/patches/patch-c_Makefile.in
$ wget http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/devel/doxymacs/patches/patch-c_doxymacs__parser.c
$ patch -p0 < patch-c_Makefile.in
$ patch -p0 < patch-c_doxymacs__parser.c
$ ./configure --prefix=${HOME}
$ make all install

以下のファイルがインストールされます。 

${HOME}/bin/doxymacs_parser
${HOME}/share/emacs/site-lisp/xml-parse.el
${HOME}/share/emacs/site-lisp/xml-parse.elc
${HOME}/share/emacs/site-lisp/doxymacs.el
${HOME}/share/emacs/site-lisp/doxymacs.elc

doxymacs_parserコマンドはPATHが通っている場所に、elispファイルは.emacsのサーチパスが通っている場所に設置してください。

3 .emacsの設定

requireを追加し、C/C++共通のc-mode-common-hookに追加します。 

;; doxymacs
(require 'doxymacs)
(add-hook 'c-mode-common-hook 'doxymacs-mode)

4 コメント形式の設定

.emacsでdoxymacs-doxygen-styleに値を設定することでコメント形式を設定できます。

デフォルトは"JavaDoc"です。 

(setq doxymacs-doxygen-style "JavaDoc")

 

"JavaDoc" /**
  * JavaDoc.
  */
"Qt" //!
  /*!
  Qt.
  */
"C++" ///
  /// C++.
  ///

 

5 ショートカット

個人的に使っているものを記載します。

 

C-cキー dキー iキー ファイルヘッダのコメント
C-cキー dキー fキー 関数用のコメント
C-cキー dキー mキー 複数行の空コメント
C-cキー dキー sキー 1行の空コメント
C-cキー dキー ;キー メンバコメント

 

以降ではJavaDocの例を記載します。

5.1 ファイルヘッダのコメント

C-cキー dキー iキーを押すことでファイルヘッダ用コメントのテンプレートが埋め込まれます。 

/**
 * @file   comment.cc
 * @author username <mail@address>
 * @date   Wed Sep  2 18:46:39 2015
 * 
 * @brief  
 * 
 * 
 */

@briefの行にカーソルが設定されます（移動せずにコメントできます）。

@autherにはユーザ名とメールアドレスが記載されます。ユーザ名とメールアドレスを変更する場合は.emacsで以下のcustom-set-variablesを設定します。 

(custom-set-variables
 '(user-full-name "newusername")
 '(user-mail-address "newmail@address")
)

5.2 関数用のコメント

C-cキー dキー fキーを押すことでファイルヘッダ用コメントのテンプレートが埋め込まれます。 

/** 
 * 
 * 
 * @param string
 */
void foo::set(const std::string &string)

2行目の*の後ろにカーソルが設定されます。

5.3 複数行の空コメント

C-cキー dキー mキーを押すことで複数行の空コメントが埋め込まれます。 

/**
 * 
 * 
 */

2行目の*の後ろにカーソルが設定されます。

5.4 1行の空コメント

C-cキー dキー mキーを押すことで1行の空コメントが埋め込まれます。 

///

///の後ろにカーソルが設定されます。

5.5 メンバコメント

C-cキー dキー ;キーを押すことでメンバコメントが埋め込まれます。 

 std::string mString;          /**<  */

<の後ろにカーソルが設定されます。

6 独自のコメント形式

custom-set-variablesで以下の値を設定することで、各種コメントを独自のコメント形式を用いるようにすることができます。

 

doxymacs-file-comment-template ファイルヘッダのコメント
doxymacs-function-comment-template 関数用のコメント
doxymacs-blank-multiline-comment-template 複数行の空コメント
doxymacs-blank-singleline-comment-template １行の空コメント
doxymacs-member-comment-start メンバコメントの開始文字
doxymacs-member-comment-end メンバコメントの終了文字

 

以下は１行の空コメントを///から/** */に変更した例です。ここでnは改行、pはカーソル位置の設定となります（下の例ではnはないです）。 

(defconst doxymacs-my-blank-singleline-comment-template
 '("/** " p " */" >)
 "Default my-style template for a blank singleline doxygen comment.")

(custom-set-variables
 '(doxymacs-blank-singleline-comment-template
   doxymacs-my-blank-singleline-comment-template)
)

デフォルトのままだと若干使いづらい部分があるので、改行とかをカスタマイズすると良いでしょう。

JavaDocの場合は以下の関数が使われています。 

doxymacs-JavaDoc-file-comment-template
doxymacs-JavaDoc-function-comment-template
doxymacs-JavaDoc-blank-multiline-comment-template
doxymacs-JavaDoc-blank-singleline-comment-template

メンバコメントはdoxymacs-member-comment-startとdoxymacs-member-comment-endが設定されていない場合にdoxymacs-doxygen-styleを判別するので、JavaDoc用の関数は存在しません。

6.1 個人的に使用しているコメント

JavaDocをベースに、というよりほぼまんまですが、以下を使ってます。 

(defconst doxymacs-my-file-comment-template
 '("/**" > n
   " * " (doxymacs-doxygen-command-char) "file      "
   (if (buffer-file-name)
       (file-name-nondirectory (buffer-file-name))
     "") > n
   " * " (doxymacs-doxygen-command-char) "author    "
   (user-full-name) (doxymacs-user-mail-address) > n
   " * " (doxymacs-doxygen-command-char) "copyright "
   "(c) 2015 " (user-full-name) ". All right reserved." > n
   " *" > n
   " * " (doxymacs-doxygen-command-char) "brief     "
   (p "Brief description of this file: ") > n
   " */" >)
 "Default my template for file documentation.")

(defconst doxymacs-my-function-comment-template
 '((let ((next-func (doxymacs-find-next-func)))
     (if next-func
   (list
    'l
    "/**" '> 'n
    " * " 'p '> 'n
    (doxymacs-parm-tempo-element (cdr (assoc 'args next-func)))
    (unless (string-match
                   (regexp-quote (cdr (assoc 'return next-func)))
                   doxymacs-void-types)
      '(l " * " (doxymacs-doxygen-command-char)
    "return " (p "Returns: ") > n))
    " */" '>)
       (progn
   (error "Can't find next function declaration.")
   nil))))
 "Default my-style template for function documentation.")

(defconst doxymacs-my-blank-multiline-comment-template
 '("/**" > n "* " p > n "*/" >)
 "Default my-style template for a blank multiline doxygen comment.")

(defconst doxymacs-my-blank-singleline-comment-template
 '("/** " p " */" >)
 "Default my-style template for a blank singleline doxygen comment.")

(custom-set-variables
 '(doxymacs-file-comment-template doxymacs-my-file-comment-template)
 '(doxymacs-function-comment-template
   doxymacs-my-function-comment-template)
 '(doxymacs-blank-multiline-comment-template
   doxymacs-my-blank-multiline-comment-template)
 '(doxymacs-blank-singleline-comment-template
   doxymacs-my-blank-singleline-comment-template)
)
カテゴリ： 201509, Emacs, ja