Using SRecode to generate doxygen comments for an existing C file

1
votes

I was looking for a way to automatically generate doxygen comment blocks for functions in existing source files. While looking at the alternatives I saw a reference to an existing mechanism in SRecode that could generate the correct comments with srecode-document-insert-function-comment. After enabling the tag generation with M-x semantic-mode and SRecode with M-x srecode-minor-mode. Everything seemed to be working, the templates and tables seemed to detected the c-mode when using the SRecode debugging functions.

However, when I use the SRecode->Generate menu option, instead of a doxygen function comment, I get a plain comment as follows:

/** main --
* 
*/
void main(int argc, char **argv)

I get nothing but the following messages with C-h e:

Adding srecode-insert-getset to srecode menu
Adding srecode-document-insert-comment to srecode menu

I've already tried it on other functions and tried debugging with edebug-defun but I could not make sense of the output.

Can someone suggest what other settings are necessary?

Additional details:

  • GNU Emacs 24.3.1 (i386-mingw-nt6.1.7601) of 2013-03-17 on MARVIN
  • Semantic 2.2
  • SRecode 1.2

Update 20131009:

  • retrying from different cursor positions (e.g. inside the function, on the start of the function name) produces the same results
  • calling from the menu or directly calling the function produces the same results
  • I have no special customizations in .emacs for either semantic or SRemote, and the modes are not enabled until I call them specifically as described above (Perhaps that's actually what's missing; is there some sort of global setting necessary?)

Update 20131012:

  • retried with a different PC (with different configuration) and with the -q startup option to ignore the .emacs file. In both cases, the output was the same.

Update 20131013:

  • I noticed the following in the *messages* buffer after running generate for the first time. Perhaps there's a hint in there.

    Adding srecode-insert-getset to srecode menu
Adding srecode-document-insert-comment to srecode menu
Adding srecode-insert-getset to srecode menu
Adding srecode-document-insert-comment to srecode menu
Compiling template default.srt...
2 templates compiled for default
Templates default.srt has estimated priority of 80
Compiling template c.srt...
17 templates compiled for c-mode
Templates c.srt has estimated priority of 90
Compiling template c.srt...
14 templates compiled for c-mode
Templates c.srt has estimated priority of 90
Compiling template doc-default.srt...
7 templates compiled for default
Templates doc-default.srt has estimated priority of 80
Auto-saving...done
3
emacsemacs24

3 Answers

1
votes

Looks like someone at some point moved doc-c.srt to doc-cpp.srt instead of copying it (this is emacs 24.3.1).
As a result srecode-document-insert-comment works (as you expect it to) only in c++-mode.
In order to enable it for c-mode create a file ~/.srecode/doc-c.srt with the following content and it should work fine.

;; doc-c.srt --- SRecode templates for "document" applications

;; Copyright (C) 2008-2013 Free Software Foundation, Inc.

;; Author: Eric M. Ludlam <[email protected]>

;; This file is part of GNU Emacs.

;; GNU Emacs 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.

;; GNU Emacs 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 GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.

set mode "c-mode"

set application "document"
context declaration

;;; Notes on the DOCUMENT templates.
;;
;; These templates recycle existing templates for doxygen in the
;; more general C template set.

template section-comment :indent :blank
"A comment separating major sections of a file."
----
{{>:declaration:doxygen-section-comment}}
----

template function-comment :tag :indent :blank
"A comment occurring in front of a function.
Recycle doxygen comment code from the more general template set."
----
{{>:declaration:doxygen-function}}
----

template variable-same-line-comment :tag
"A comment occurring after a variable declaration.
Recycle doxygen comment code from the more general template set."
----
{{>:declaration:doxygen-variable-same-line}}
----

;; These happen to be the same as in a classdecl.
template group-comment-start :blank :indent
"A comment occurring in front of a group of declarations.
Recycle doxygen comment code from the more general template set."
----
{{>:classdecl:doxygen-function-group-start}}
----

template group-comment-end :blank :indent
"A comment occurring at the end of a group of declarations.
Recycle doxygen comment code from the more general template set."
----
{{>:classdecl:doxygen-function-group-end}}
----

;; end

An alternative for doxygen comment generation would be doxymacs

0
votes

You should be on the same line as function name, or inside function's definition - then, srecode-document-insert-comment (C-c / C) will insert correct comment. Here is result of this command on my CEDET installation (from bzr, although in 24.3.1 it should be the same):

/**
 * @name main - 
 * @param argc - Number of arguments
 * @param argv - Argument vector
 * @return int
 */
int main(int argc, char **argv) {

    return 0;
}
0
votes

Your cursor should be before the opening parenthesis. If you are inside the parameter list nothing will be inserted.