Eu estou desenvolvendo uma API
Então qual o problema em definir a API usando classes e interfaces e documentar o que cada método deve fazer?
Exemplo:
/**
* 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
}
Enfim, tudo vai para o Javadoc, aí basta o programador seguir o que está ali.
o que eu quero fazer mesmo é escrever manualmente tudo que a API deve ter e formatar em documentação antes de criar o código
Use Word ou qualquer editor de texto. Talvez uma ferramenta colaborativa como Confluence (nota: eu trabalho para a Atlassian) seja melhor por facilitar o trabalho de várias pessoas e versionamento do documento.
Diagramas UML específicos podem ser adicionados onde você precisar.
um lugar onde tenha campos para classes, variáveis, métodos, enums etc,
Crie uma tabela como modelo. Não precisa de uma ferramenta para isso, basta ter um mínimo de disciplina para documentar.
Os programas de UML são muito ruins, é horrível ter que representar graficamente (quadrados e setas pra todo lado)
Eu concordo que a maioria é horrível. O melhor que eu conheço é o Enterprise Architect, que usei algumas vezes para criar documentos de arquitetura de novos sistemas que iam ser desenvolvidos.
Entretanto, dizer que fica confuso por causa do programa não é verdade. Provavelmente você precisa se familiarizar melhor com UML e com a ferramenta.
Com UML porque você não precisa representar 100% do programa em diagramas, apenas os conceitos mais importantes.
Com a ferramenta porque você pode distribuir os objetos em diferentes diagramas para cada caso de uso. Tentar modelar tudo em um diagrama gigante não é boa prática.