Проектирование API-интерфейсов на Java с использованием нисходящего подхода. Является ли составление документации Javadoc лучшей отправной точкой?
Всякий раз, когда мне нужно разработать API на Java, я обычно начинаю с открытия моей IDE и создания пакетов, классов и интерфейсов. Реализации методов являются фиктивными, но документация javadoc подробно описана.
Это лучший способ решить эту проблему? Я начинаю чувствовать, что документация API должна быть выпущена первой - даже до того, как будет написан первый файл .java. Это дает несколько преимуществ:
- Разработчик API может завершить проектирование и спецификацию, а затем разделить реализацию между несколькими разработчиками.
- Более гибкий - изменение дизайна не требует, чтобы кто-то прыгал среди java-файлов в поисках места для редактирования комментария javadoc.
Есть ли другие, кто разделяет это мнение? И если да, то как начать с разработки API?
Кроме того, есть ли какие-нибудь инструменты, которые могут помочь? Возможно, даже какой-то инструмент на основе аннотаций, который генерирует документацию, а затем исходный скелет (вроде генераторов модели в код)? Я столкнулся с инструментарием Eclipse PDE API - но он специфичен для проектов плагинов Eclipse. Ничего более общего не нашел.