Документирование процессов в java-коде в Eclipse

В своих Java-приложениях я всегда комментирую свои классы и методы, чтобы указать, для чего они предназначены. Проблема, с которой я часто сталкиваюсь, заключается в документировании полного процесса, в результате чего процесс распределяется по нескольким классам. Мне нужно задокументировать, как все части работают вместе, чтобы дать простой обзор того, как что-то работает.

Я нахожу проблематичным то, ГДЕ я пишу эту документацию. С таким же успехом я мог бы написать его в отдельном файле, таком как документ Word, но документация имеет тенденцию отчуждаться от фактического кода, и возможна рассинхронизация. С другой стороны, если я задокументирую это в одном файле кода Java, кому-то, читающему один из зависимых классов, будет сложно узнать, как этот класс вписывается в общий процесс, если только он не знает о документации в классе, где я написал это. Возможное решение состоит в том, чтобы просто включить ссылку в каждый класс, составляющий весь процесс, и просто обозначить один из классов как «основной» класс, из которого исходит документация.

Или есть лучший альтернативный подход к тому, как я должен это делать?

ИЗМЕНИТЬ:

Например, у вас есть мобильное приложение, которое загружает данные на сервер, а затем вы загружаете данные с сервера на другое устройство. У вас есть процесс, который охватывает три компонента (отправляющее мобильное устройство, сервер и принимающее мобильное устройство). Ни один из них нельзя в действительности считать «отправной точкой в ​​общем процессе передачи данных, поэтому при документировании этого процесса куда пойдет эта документация?


person AndroidDev    schedule 29.07.2013    source источник
comment
Можете ли вы использовать @link для связи других классов?   -  person AllTooSir    schedule 29.07.2013
comment
Возможно, вы сможете использовать javadoc для этого. Файл package-info.java позволяет вам писать документацию в виде пакета. stackoverflow.com/q/624422/53897   -  person Thorbjørn Ravn Andersen    schedule 29.07.2013
comment
Я использую javadoc для классов и методов, но это не дает никакого решения для документирования всего процесса.   -  person AndroidDev    schedule 29.07.2013
comment
Ну, зависит от того, как вы его используете. Вы можете разместить различные ссылки на странице пакета.   -  person Thorbjørn Ravn Andersen    schedule 29.07.2013
comment
О какой странице пакета вы говорите? Никогда об этом не слышал.   -  person AndroidDev    schedule 29.07.2013