Max Home IndustryAPIMiner только что достиг версии 2.0, и если вы не знаете об этом, вы можете упустить полезный инструмент и действительно хорошую идею.
Когда вы документируете API, самое меньшее, что вы можете сделать, — это перечислить классы, методы и свойства. Каждый метод также должен документировать свои параметры, и JavaDoc-хороший способ сделать ваш код более или менее автодокументированным. Но… не было бы неплохо добавить пример использования каждого из методов API?
Большая проблема заключается в том, что для поиска примеров требуется время — много времени, если API, который вы документируете, большой, как API Android. Вот тут-то и появляется АПИМинер. Он автоматически добавит пример, взятый из кода, который реализует или использует API.
Он сканирует API и составляет список методов. Затем он сканирует репозиторий кода, чтобы найти применение методов. Затем он находит блок кода, который показывает используемый метод, и выбирает лучший из всех таких примеров. Наконец, он вставляет примеры в JavaDoc.
На данный момент APIMiner был применен только к API Android, и вы можете использовать его либо как веб-сайт, либо как дополнение к Eclipse или Android Studio. В любом случае вы получаете обычный JavaDoc плюс кнопку, которая показывает вам пример использования метода, если вы нажмете на нее.
APIMiner кажется хорошей идеей, хотя тщательно созданная документация все равно будет лучшим вариантом во всех случаях. Жаль, что в настоящее время он применяется только к документации Android. Возможно, решением было бы превратить его в проект с открытым исходным кодом. В настоящее время система разработана и поддерживается Исследовательской группой по прикладному программному обеспечению (ASERG) Факультета компьютерных наук Федерального университета Минас-Жерайс, Бразилия, и является результатом работы над магистерской диссертацией.