Software to create documentation without using source code

  

I'm 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 it is enough for the programmer to follow what is there.

  

What I really want to do is to manually write everything the API should have and format it into documentation before creating the code

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

Specific UML diagrams can be added wherever you need them.

  

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

Create a table as a template. You do not need a tool for this, just have a minimum of discipline to document.

  

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

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

However, saying that you are confused because of the program is not true. You probably need to become more familiar with UML and with the tool.

With UML because you do not need to represent 100% of the program in diagrams, just the most important concepts.

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

There is something in Eclipse (not if it's the IDE it uses) that lets you assemble the classes with their members by a basic form and it generates the code. This can simplify code making a little, eventually it may even generate some comments that already help with the documentation.

There may be some plugin that goes beyond this and makes it easier, but do not expect too much. I've seen something for other IDEs / languages, but there must be something for Java.

I agree that doing the entire UML is not always desirable, but it can be a reasonable solution if you just want to manage the contracts without major implications. You do not have to do everything perfectly, state relationships, etc.

Even if you do not have the solution is to write the API public contracts. Something that is useful regardless of whether it is used to create documentation.

These documenters can not actually document, they just get information available in the code to generate text in a specific format. They can do something with the defined contracts (classes, interfaces, methods, etc.). Everything that is public would be documented. In thesis it is possible to do with the private parts too, but it is not usually suitable because it is implementation detail and not part of the API.

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