Show part of method body in documentation

Question

I want to show part of method body in its documentation (JavaDoc).

For example:

/**
 * The algorithm contains steps:
 * @showMethodBody
 */
public void algorithmX(int coordinateX) {
    makeStep1();
    if (coordinateX == TOP) {
        makeStep2();
    }
}

Which should produce documentation like:

    The algorithm contains steps:
    makeStep1();
    if (coordinateX == TOP) {
        makeStep2();
    }

I know that such documentation is a bit silly and it's not in natural language. But the best thing is that it never be out of date.

So general concepts could be described in natural language, but crucial elements may be copied directly from source code. As you see source code could be informative for not programmer also. And here is my question:

Question:

How to copy (show) part or whole method body inside method's documentation?

Now I'm using JavaDoc, but I can also use any other tool. I can also add some pointers (annotation or special comments) in source code if it will help.

Why would you want to do this? Write your JavaDocs like the method is a black box: These inputs go in, *magic happens*, then this output comes out. *How* a set of inputs becomes the output should be irrelevant to the reader, and if they're *really* that interested they can read the source. — JonK, Apr 10 '19 at 15:11
@JonK Because our users want documentation with business details - so I need expose some details about behaviour of my code. And of course I can describe this using natural language: `Algorithm do step1 and step2 if coordinateX is equal to TOP` or I can put real code in docs. — jsosnowski, Apr 10 '19 at 15:58

score 1 · Answer 1 · answered Apr 10 '19 at 15:44

In doxygen there are a couple of possibilities:

INLINE_SOURCES, disadvantage here is that for all functions all the code will be included
commands dontinclude, together with \skip, \line etc. to include parts of a file.
\snippet command where one marks certain parts of the code and can place them in the documentation

See also the doxygen manual at http://www.doxygen.nl/manual/ in this case the chapters "Special Commands" and "Configuration"

Show part of method body in documentation

1 Answers1