Припустимо, ви працюєте в ІТ-відділі великої компанії. Ваш бос інструктує вас, що треба написати програму, що складається з декількох тисяч рядків вихідного коду. Через кілька тижнів ви закінчите програму і запустіть проект. Через кілька місяців користувачі починають помічати, що програма іноді падає. Вони скаржаться вашому босу, а він, у свою чергу, наказує вам: необхідно виправити це. Пошукавши в вашому архіві проектів, ви знаходите папку з текстовими файлами - вихідний код програми. На жаль, ви виявляєте, що вихідний код не має сенсу - він просто-напросто вам незрозумілий. За минулий час ви працювали в інших проектах, і ви не можете згадати, чому ви написали код саме так. Розшифровка коду може зайняти кілька годин або навіть днів, але босові потрібен результат ще вчора. Неминучий чималий стрес. Як же не допустити цього?
Даного стресу можна уникнути, якщо документувати вихідний код значущими описами. І хоча це часто не береться до уваги, але документування вихідного коду при написанні логіки програми - це одна з найбільш важливих завдань розробника. Як можна побачити з мого прикладу, враховуючи деякий час, який минув від часу написання коду, навіть прекрасний програміст може не зрозуміти обгрунтування деяких рішень - чому він зробив саме так, а не інакше.
Розглянемо часто використовуються наразі Javadoc:
Генерируемая документація включає в себе індексний файл (index.html), який представляє собою стартову сторінку. Наприклад, на малюнку нижче ви можете бачити стартову сторінку з документації Java SE 8 update 45 бібліотеки API, згенерувала Javadoc.
