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.
Cite a program that generates documentation. I know programs that format documentation. Unless you’re talking about something very trivial that doesn’t serve much purpose. Anyway, the documentation doesn’t look at the algorithm, just the contract. If you do not want to do UML (I agree with you) write the contracts, describe the API in code itself and have the "documented" generate the text. Then you implement the behaviors and implementation details that are independent of the API.In fact, this is what everyone should do in most situations.Give me more information to see if I can turn it into a response.
– Maniero
Thank you, if I do not find anything I really think I will have to fill up with empty methods, but the excess of comments also hamper the reading of the code, unfortunately
– Rodrigo Santiago