CODEWITHSUNDEEP
documentationd
David Shaked
David Shaked

Reputation: 3381

Does D support documentation generation?

Many modern programming languages support a system of comments as documentation strings.

This feature is taken for granted in languages like Python or Clojure, where documentation strings may be useful in understanding the purpose of a function that might be unclear otherwise:

def gen_ast(s):
    ''' given a string, s, representing a program, generates object model of abstract syntax tree '''
    # function contents here ...

I am fairly novice in D programming, but have not yet found documentation for writing documentation string comments in a way that's accessible to the client (e.g., help(gen_ast) in Python). Does D provide support for docstrings?

Upvotes: 2

Views: 79

Answers (2)

David Shaked
David Shaked

Reputation: 3381

As a follow up to @Adam D Ruppe's answer, here's the relevant content from extracted from the first link, which is the official specification for D documentation generation.

First, returns of functions are specified as follows:

 /**
 * Read the file.
 * Returns: The contents of the file.
 */

void[] readFile(char[] filename) { ... }

Secondly, examples are specified in a similiar manner where needed:

/**
 * Examples:
 * --------------------
 * writeln("3"); // writes '3' to stdout
 * --------------------
 */

However, I found the documentation unclear with respect to the ability of using these conventions for automatic documentation generation.

Upvotes: 1

Adam D. Ruppe
Adam D. Ruppe

Reputation: 25605

Yes.

For code itself: http://dlang.org/spec/ddoc.html

For options on the command line: http://dlang.org/phobos/std_getopt.html

To get from the code: http://dlang.org/spec/attribute.html#uda

However, it is fair to pout out that the doc comment is not accessible directly in code - you will have to do it as a UDA or getopt library documentation string, or have a separate command in your build set to extract the comments (dmd -D makes them into html, dmd -D -X will make them into json, then you parse that)

Upvotes: 3

Related Questions