Software to create documentation without using source code

Question

I’m developing an API, very big, and I want to create the documentation, but most of the programs I found just take the documentation from the comments of the code-source, what I really want to do is write manually everything the API should have and format in documentation before to create the code, and build on the basis of documentation, as a kind of UML.

It may sound crazy, but it helps a lot. UML programs are very bad, it’s horrible to have to act graphically (squares and arrows everywhere), I get lost so big that it is.

I am looking for something very simple, just a place where you have fields for classes, variables, methods, enums etc, just to type same text and create pages in HTML or PDF.

Answer 1

I am developing an API

So what’s the problem in defining the API using classes and interfaces and documenting what each method should do?

Example:

/**
 * Esta classe deve implementar comportamentos comuns a todos os animais
 */
abstract class Animal {
    /**
     * Consome uma implementação de {@link Comida}.
     * @param comida O animal pode rejeitar a comida se não for do tipo que ele gosta
     * @throws AnimalNaoPodeComerIssoException
     */
    abstract void comer(Comida comida);
}

/**
 * Interface implementada por animais que voam.
 */
interface Voador {
    /**
     * Desloca o animal até o local especificado.
     * @param local Onde o animal deve pousar
     */
    void voar(Local local);
}


/**
 * Detalhes sobre como implementar um Pombo...
 */
class Pombo extends Animal implements Voador { 
    //detalhes sobre como implementar os comportamentos específicos
}

Anyway, everything goes to Javadoc, then just the programmer follows what is there.

what I really want to do is write manually everything the API should have and format in documentation before creating the code

Use Word or any text editor. Maybe a collaborative tool like Confluence (note: I work for Atlassian) is better for facilitating the work of several people and versioning the document.

Specific UML diagrams can be added where you need them.

a place where you have fields for classes, variables, methods, enums etc,

Create a table as a template. You don’t need a tool for this, just have a minimum of discipline to document.

UML programs are very bad, it’s horrible to have to represent graphically (squares and arrows everywhere)

I agree that most are horrible. The best I know is the Enterprise Architect, which I used a few times to create architectural documents of new systems that were going to be developed.

However, saying that you get confused because the program is not true. You probably need to get better acquainted with UML and the tool.

With UML because you don’t need to represent 100% of the program in diagrams, only the most important concepts.

With the tool because you can distribute the objects in different diagrams for each use case. Trying to model everything on a giant diagram is not good practice.

Answer 2

There’s something in Eclipse (I don’t know if it’s the IDE you use) that allows you to assemble classes with your members through a basic form and it generates the code. This can simplify the code a little, eventually can even generate some comments that help the documentation.

It is possible that there is some plugin that goes beyond this and makes it a little easier, but don’t expect too much. I’ve seen something for other Ides/languages, but there must be something for Java.

I agree that making the whole UML is not always desirable, but it can be a reasonable solution if you just want to manage the contracts without major implications. You don’t have to do everything perfectly, indicate relationships, etc.

Even if you don’t have the solution is to write the API’s public contracts. Something useful regardless of being used to create documentation.

These documenting software can’t actually document, they just take information available in the code to generate text in a specific format. They manage to do something with the defined contracts (classes, interfaces, methods, etc.). Everything that is public would be documented. In theory it is possible to do with private parties as well, but it is not usually suitable because it is implementation detail and is not part of the API.

To have more relevant information you will have to write documented comments. It will be almost entirely manual. Automation will be minimal.