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.

Answer 1

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"