2

I want to implement a simple utility that would take a C source file and a name of a function, struct, enum or whatever and output the comment directly above the element if present.

Ie.

/* This is a doc comment
 * I want this comment extracted
 */
void function_foo(){

}

Usage:

utility file.c function_foo

Output:

This is a doc comment 
I want this comment extracted

The use case for this is that I want to use org-babel in emacs to tangle in documentation for functions right out of source files. Maybe there is a doxygen tool or clang tool that can do this? I just haven't found it yet. The end result would be that I can easily keep up to date documentation extracted from code directly inside my documentation org file that contains other things as well.

  • No extraction of c++-style // comments? Can there be /*more*/ than one /*comment*/ in a line? And is there a chance that literal c strings contain /* (char* foo = "Break your /* regexp";)? – Philippos May 22 at 5:28
  • One thing I love about Go is that its designers recognized that a language doesn't exist in a vacuum—it needs a toolchain. So in Go, the method you describe is THE way to keep your code documented, and go doc will extract it for you with no extra work. :) – Wildcard May 22 at 5:55
0

Try:

utility() {
  FUNC=$2 perl -l -0777 -ne '
    if (
      m{
        ^ /\* \s* ((?s:(?!\*/).)*?) \s* \*/ \s* \n
        (?:\w.*\h)? \Q$ENV{FUNC}\E \h* \(
      }mx
    ) {
      $comment = $1;
      $comment =~ s/^\s*\*\s*//gm;
      print $comment
    }' < "$1"
}

It assumes the comment and function definition are right at the start of the line (without leading blanks) to avoid false positives with the function's invocations.

Now, before re-inventing the wheel, you may want to look at things like doxygen which provide a framework for code-based documentation.

  • I am looking for a solution that would tie well into emacs org mode. I want a workflow where I can write doc with headings, markdown, dates, time etc in org minor mode right in the source file and then do org babel tangle and get the comment inserted into the linked section in the org file for documentation. Now that file will contain manually written data as well so this needs to work on tagged sections. One solution I was thinking about is to do this in reverse where in org mode I make sections with shell command and function name and get the comment imported as result. – Martin May 22 at 14:38
  • Do you know if it is possible to export doxygen comments as markdown files with docs for one function per file? Maybe that can be an option. Then I can just use include tags in the org doc and get an error if any file goes missing. That would be very neat actually. – Martin May 22 at 14:42
  • @Martin sorry I'm not familiar with doxygen – Stéphane Chazelas May 22 at 15:40

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.