\documentclass[../j-spec.tex]{subfiles}

\begin{document}
\showslide{build/jc-1-b.pdf}
Добро пожаловать на специализацию Java, лучшую из всех специализаций Java, что вы сможете найти.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Здравствуйте, меня зовут Иван, я разработчик программного обеспечения в Российских космических системах, начальник группы программистов, автор и преподаватель нескольких курсов в направлении программирования на портале GeekBrains. Пара слов обо мне, почему я нахожусь здесь и планирую Вам что-то рассказывать про язык Java? Для этого придётся вынести за скобки мой опыт работы в цифровой схемотехнике и других языках, в том числе создание бортовой аппаратуры, которая прямо сейчас летает у нас над головами или продолжает доставлять другие полезные грузы в космос. С точки зрения языка Java, обо мне можно сказать, что я являюсь разработчиком нескольких отраслевых информационных систем поддержки единой наземной инфраструктуры российского космического агентства. На моём счету также участие в межотраслевых проектах по созданию единых баз данных космического применения.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Данный курс, первый из специализации, направлен на первое знакомство со внутренним устройством языка и фреймворком разработки приложений с его использованием. Курс демонстрирует механизмы работы знакомых студенту концепций на примере языка Java. В рамках курса будут рассмотрено устройство языка Java и сопутствующих технологических решений, платформы для создания и запуска приложений на JVM-языках (Groovy, Kotlin, Scala, и др). Будут рассмотрены некоторые базовые пакеты ввода-вывода, позволяющие манипулировать данными за пределами программы. В результате прохождения курса у вас, слушатели, должно появиться знание принципов работы платформы Java, понимание того, как язык выражает принципы программирования, его объектную природу. Вы научитесь писать базовые терминальные приложения и утилиты, решать задачи (в том числе алгоритмические, не требующие подключения сложных библиотек) с использованием языка Java и с учётом его особенностей.

На этом уроке мы поговорим о
\begin{itemize}
\item краткой истории и причинах возникновения язка
\item что нужно скачать, откуда и как это всё выбирать
\item из чего всё состоит
\item изучим простую структуру проекта и способы его запуска
\item коротко рассмотрим утилиту джавадок
\end{itemize}
Рассмотрим примитивный инструментарий и базовые возможности платформы для разработки приложений на языке Java. 

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Итак язык Java. Согласно википедии, Java — строго типизированный объектно-ориентированный язык программирования общего назначения, разработанный компанией Sun Microsystems. Разработка ведётся сообществом; язык и основные реализующие его технологии распространяются по лицензии GPL.

Приложения Java обычно транслируются в специальный байт-код, поэтому они могут работать на любой компьютерной архитектуре, для которой существует реализация виртуальной Java-машины. Дата официального выпуска — 23 мая 1995 года. Традиционно занимает высокие места в рейтингах популярности языков программирования (3-е место в рейтинге TIOBE (на август 2021)). На графике отлично видно, что с 2002 года язык уверенно держится в тройке популярных, значительную часть времени возглавляя его.

Но это всё - сухие факты, ничего не говорящие нам о том, чем руководствовались разработчики языка и что нам, программистам, с этим делать.

Существует, интересная версия происхождения названия языка, связанная с аллюзией на кофе машину как пример бытового устройства, для программирования которого изначально язык создавался. Кстати, в результате работы проекта мир увидел принципиально новое устройство, карманный персональный компьютер, который опередил своё время более чем на 10 лет, но из-за большой стоимости не смог произвести переворот в мире технологии и был забыт. Устройство Star7 не пользовалось популярностью, в отличие от языка программирования Java и его окружения. С середины 1990-х годов язык стал широко использоваться для написания клиентских приложений и серверного программного обеспечения. Тогда же некоторое распространение получила технология Java-апплетов — графических Java-приложений, встраиваемых в веб-страницы; с развитием возможностей динамических веб-страниц технология стала применяться редко и язык стал применяться для бэк-энда.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Итак Язык программирования Java занял свою нишу в системном и прикладном программировании из-за своей высокой скорости работы, и веб-программировании, из-за удобного сетевого окружения, ставшего основой для создания бэк-энда веб-сервисов. Java очевидно испытал влияние языков C, C++, Pascal и других, так что многое в этих языках достаточно досконально изучить один раз, чтобы иметь возможность понимать все связанные.

Поскольку язык изначально проектировался для множества разнообразных исполнителей с разными архитектурами процессоров и систем, было принято решение отделить исполнителя от решаемой прикладной задачи, так появилась виртуальная машина Java, речь о которой пойдёт немного позже. Основной смысл в том, что у языка Java появился девиз: Написано однажды, работает везде.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Мы привыкли к тому, что для программирования нужна некоторая среда, которая будет удобно подсказывать нам, что делать, как писать программу, запускать написанный код и помогать нам отлаживать его. Чаще всего это так, но я призываю вас не останавливаться на единственном инструменте, ведь если быть всегда сосредоточенным на отвёртке, вы никогда не узнаете, что люди придумали очень удобный шуруповёрт.

Я не планирую рекламировать ту или иную среду, скорее всего не буду даже много говорить о плюсах и минусах той или иной среды, просто покажу список и коротко расскажу о главных действующих лицах:
\begin{enumerate}
\item NetBeans - если коротко, то эта среда с нами из уважения к истории, она была первой, созданной для разработки на языке Java. Долгое время разработка этой среды не велась, но в последние несколько лет разработчики как будто бы вспомнили о ней и активно взялись за дело, сейчас есть версии под все популярные ОС, поддерживается весь популярный современный функционал, есть прикольные самобытные моменты, вроде расширенных клавиатурных макросов для написания функций с передаваемыми в них массивами;
\item Eclipse - проще, наверное, назвать язык или технологию, под которую нет плагина для этой весьма расширяемой и дополняемой среды программирования. Долгое время, вплоть до недавнего, а где-то и до сих пор, является корпоративным стандартом для написания Enterprise приложений и прочих сложных корпоративных приложений. Весьма гибкая среда и-за того, что разрабатывается Eclipse Foundation к ней можно подключить плагины, решающие почти любые задачи разработки. Из того что я видел своими глазами, Siemens использует Eclipse для разработки своих систем поддержки жизненного цикла изделий;
\item IntelliJ IDEA - стандарт де-факто примерно десять последних лет. Не уверен, можно ли назвать эту среду российской разработкой, но у компании, разрабатывающей эту среду, три русских учредителя. Да и сама эта компания началась именно с этой среды. В этой среде можно настроить почти любую деталь, что часто бывает очень удобно. Среда расширяется плагинами на почти все случаи жизни разработчика. Часто входит в экосистему JetBrains, развёрнутую на предприятии, поэтому тесно интегрируется в другие сферы деятельности компании. Существует как бесплатная, так и платная версия с расширенным функционалом, например, доступа к базам данных.
\end{enumerate}

Отдельно стоит обговорить такую среду, как Android Studio, как мог заметить внимательный зритель, её нет в списке на слайде, но не потому, что в ней нельзя разрабатывать Java-приложения, а потому что если не разрабатывать в ней именно Android приложения, следует отказаться от её использования из-за некоторой избыточности. Среда снабжена значительным количеством надстроек и эмуляторов мобильных устройств, которые попросту будут вам мешать, если вы не используете их в своей профессиональной деятельности. С другой стороны, если ваша цель - это именно мобильная разработка под Android, то и выбора у вас особо нет, только Android Studio.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Для разработки на языке Java вам может понадобиться довольно много разного инструментария, тем более, что требования к инструментарию отличаются ещё и от команды к команде, вам может потребоваться средство для работы с БД, средства моделирования и описания систем, дополнительные средства документирования кода и решений. Но совершенно точно можно сказать, что без двух вещей обойтись не удастся: это иде, они же среды программирования и ждк, он же инструментарий разработчика на java. О средах программирования дополнительно только что поговорили, нужно выбрать какую-нибудь, и скачать. Скорее всего вы это сделали для прохождения более ранних курсов, сейчас сможете для себя выбрать инструмент более осознанно. В курсе, кроме этой лекции и следующего за ней семинара, будет использоваться комьюнити версия среды Intellij IDEA, можете для простоты выбрать её, что вы уже скорее всего и сделали. Наверняка, для прохождения предыдущих курсов вы уже скачали и установили JDK какой-нибудь хорошей новой версии, а сейчас пришла пора разобраться, что это, какие они бывают, откуда их брать и как их выбирать, мы же за осознанность как-никак.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Итак, вендоры и версии. JDK развивается, поэтому выходят новые версии, исправляющие предыдущие недочёты, добавляющие новую функциональность. Самая распространённая версия в современной российской действительности - восьмая, но есть очень серьёзный тренд на переход к 11 и 13й версиям, на более новые часто смотрят с опаской. Распространённых вендоров три - оракл, опен, либерика. Есть, конечно, компании, собирающие свой инструментарий из открытых источников самостоятельно, но их крайне мало. Про экзотических вендоров рассказывать смысла не много, важно помнить, что они есть и у них у всех разные лицензионные политики. Я в курсе буду использовать либерику, как делаю последние несколько лет, хотя довольно долгое время пользовался ораклом. Поскольку я работаю в около- государственной компании, не могу не упомянуть о ГОСТ джаве, которая часто всерьёз рассматривается в организациях, подобных моей, и об опенЖДК, который является основой для самостоятельных сборок инструментария.

Наиболее популярной, конечно, является оракл ждк, но, если мне будет позволено высказать персональное мнение, это больше дань традиции, нежели какая-то жизненная необходимость. 

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Если внимательно посмотреть на компании, внесшие вклад в развитие открытой части инструментария, начиная с ждк11 и до актуального на сегодня ждк18, конечно, максимально вкладывается оракл, но и беллсофт, производитель либерики, там будет в первой десятке. Повторюсь, я на курсе буду использовать либерику ждк11, благо для неё есть и докер-образ, если нужно как-то автоматизировать сборки вашего приложения, например; вы можете использовать любую другую не старше 8. Все примеры я буду приводить с учётом именно 8й версии языка, чтобы рассмотреть подходящий подавляющему большинству людей инструментарий. Если у вас уже установлена 11я версия от другого вендора - ничего менять не нужно, если установлена более новая версия, есть вероятность, что некоторые примеры будут отмечаться как чрезвычайно устаревшие, возможно, эти предупреждения на этапе обучения следует игнорировать. Для выбора вендора внимательно ознакомьтесь с лицензией, а для выбора версии языка руководствуйтесь здравым смыслом: большинство компаний в России и мире работают на 8, 11 или 13й версиях. Зачем учиться на какой-нибудь 18-й версии, если потом на работе вы не увидите половины каких-нибудь новых фич и фактически, придётся переучиваться?

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Для решения некоторых несложных задач курса мы будем писать простые приложения, не содержащие ООП, сложных взаимосвязей и проверок, в этом случае нам понадобится Jupyter notebook с установленным ядром (kernel) IJava. Да, многие думают, что Jupyter ноутбуки - это только для языка пайтон или для скриптовых языков, но это не так. Архитектура юпитер ноутбука позволяет ему работать с любым ядром, главное, чтобы ядро умело корректно интерпретировать написанное в ячейке с кодом. Ядро IJava делает именно это - интерпретирует Java-код, используя установленный на компьютере разработчика JDK.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Очень часто в интернете, при скачивании какого-то программного обеспечения, связанного с Java можно увидеть разные аббревиатуры: JRE, JVM, JDK и тому подобные, и чтобы в них не запутаться давайте коротко и быстро разберёмся что они значат, потому что я чувствую, как вам уже начинают надоедать все эти вступления. 

Пойдём от самого масштабного и общего к самому маленькому и частному. Самая масштабная и общая аббревиатура - это JDK Java Development Kit - инструментарий разработчика на языке Java. Это обычный SDK который содержит в себе также всё необходимое для разработки именно на языке Java здесь есть куча других аббревиатур, компилятор, средства развёртывания, создания документации, итд они позволяют удобно писать программы на языке Java и абстрагируют программиста от необходимости описывать все вспомогательные процессы непосредственно на языке программирования то есть, грубо говоря это некие классы которые инкапсулирует сложное преобразование текста программ в простой интерфейс разработчика.

Всё, что разрабатывает разработчик, исполняется в специальной среде это среда является частью JDK и позволяет исполнять все программы написанные разработчиками на конечном в компьютере. Именно эта среда и устанавливается на компьютере пользователя чтобы пользователь мог запускать приложения, написанные на языке Java. Итак, самая необходимая вещь для любого пользователя это JRE. Это аббревиатура расшифровывается как Java Runtime Environment, то есть среда исполнения программ на языке Java. Она содержит в себе основной внутренний механизм который называется Java virtual machine и библиотеку из разных классов чтобы эта виртуальная машина хорошо работала умела показывать пользователю строки осуществлять ввод-вывод фреймворк коллекций и прочее, тут тоже есть куча интересных аббревиатур, которые мы так или иначе изучим, например, Java native interface, Java database connectivity и другие. Если копнуть ещё чуть глубже, можно и JRE разделить на JSE и JEE, но нас это деление пока не очень интересует, оно произойдёт естественным образом на более старших курсах. Пока что всё, что мы будем изучать, это JSE.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Инструментарий разработчика мы будем так или иначе рассматривать весь оставшийся курс, части среды исполнения мы тоже будем всесторонне изучать на последующих уроках. Сейчас хотелось бы подробнее остановиться на виртуальной машине Java, поскольку понимание того, как она устроена, должно значительно облегчить для вас понимание процесса исполнения программы и, как следствие, процесс разработки этих самых программ. Виртуальная машина Java осуществляет загрузку классов программы в оперативную память, причём здесь имеется ввиду не оперативная память как аппаратная часть компьютера, а некая выделенная часть этой оперативной памяти, которой с нами поделилось операционная система. Также осуществляется управление памятью, а именно очистка и сборка мусора и непосредственное исполнение классов нашего приложения, путём компиляции методов из промежуточного байткода в непосредственные вызовы операционной системы или другого исполнителя, то есть грубо говоря преобразования классов Java в ассемблерный код конкретного компьютера. Этот процесс называется JIT компиляция. Существуют разные Реализация виртуальных машин (\href{https://ru.m.wikipedia.org/wiki/Список_виртуальных_машин_Java}{Wikipedia: Список виртуальных машин Java}), даже экзотические, например мультиязыковой интерпретатор GraalVM. По большей части виртуальные машины отличаются как раз этой частью, с Just In Time компиляцией, то есть с преобразованием методов в непосредственные машинные вызовы в реальном времени. Чем быстрее происходит эта JIT компиляция, тем, соответственно, быстрее работает приложение на виртуальной машине. JVM самостоятельно осуществляет сборку так называемого мусора, что значительно облегчает работу программиста по отслеживанию утечек памяти, но, на мой взгляд, не способствует должной концентрации внимания программиста на этом вопросе. Важно помнить, что в Java утечки памяти всё равно существуют, особенно при программировании многопоточных приложений. 

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Ну, наконец-то проект. Проекты бывают разной сложности, сейчас поговорим о проектах без применения сборщиков, потому что сборщикам и соответствующим проектам у нас будет посвящено отдельное занятие. Все проекты по сложности структуры можно разделить на четыре основные категории: простейшие, обычные, шаблонные, скриптовые.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Начнём с простейшего проекта, который будет состоять из одного файла исходников. Естественно, вы спросите, что за чушь, мы же уже сотни раз писали «привет мир» и запускали его удобной зелёной стрелочкой в ИДЕ. Есть ответ. Мы же выясняем, что там внутри, под капотом этих удобных стрелочек и привычных процессов. Да и ради простейшего проекта запускать тяжеловесную среду программирования как-то неестественно что ли.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Пока далеко не ушли от простейших проектов, думаю, целесообразно будет проговорить о скриптовых возможностях Java. Поскольку язык является не только компилируемым, но и интерпретируемым благодаря работе JVM, его возмжоно использовать как скриптовый внутри юпитер ноутбука, подключив соответствующее ядро. Интересной особенностью юпитер ноутбука является разделение фронтенда и ядра, что даёт возможность заменять эти самые ядра (в терминах юпитера они называются кернелы). скачав и установив ядро IJava мы получаем шикарную возможность делать простые наброски логики, снабжая их комментариями в формате маркдаун. На самом деле можно делать и непростые наброски, но это выходит далеко за рамки нашего курса о языке. Если будет очень интересно, призываю вас самостоятельно почитать о возможностях ядра, благо на него очень хорошая документация с примерами. 

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Как я сказал в начале этого блока, шаблонные проекты, создаваемые сборщиками мы обсудим на следующей лекции, поэтому осталось только поговорить о том, из чего состоит обычный простой проект. Итак чаще всего, это  пакеты, классы, метод main, комментарии, ресурсы. Обо всём по порядку. Давайте сразу договоримся, что я сначала буду давать формальное понятие, а потом буду говорить, как его можно представить в более простом виде.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Пакет - это пространство имён языка. Теоретически, как мы видели на примере простейшего проекта, класс может не находиться в пакете, но на практике такого положения дел не встретить. Например, в проекте из нескольких модулей классы без пакетов просто не будут найдены. Пакет - это некоторое место хранения и создания иерархии классов проекта. Проще всего представить пакет как папку на диске, тем более, что в файловой системе пакеты так и показываются. Но пакет - это чуть более сложная сущность. Для пакетов существуют модификаторы доступа, классы, находящиеся в одном пакете доступны друг другу даже если находятся в разных проектах (это как раз и есть отличие пакетов от папок на диске). Для нас пока достаточно, что пакеты объединяют классы по смыслу. У пакетов есть правила именования: обычно это обратное доменное имя (например, для гб.ру это будет ру.гб), название проекта, и далее уже внутренняя структура. Пакеты следует писать латинскими строчными буквами. Чтобы явно отнести класс к пакету недостаточно его просто туда положить, нужно ещё прописать в классе название пакета после специального оператора package.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Класс - это основная единица исходного кода программы. Без класса не может начаться никакое программирование на языке Java. Даже скомпилированные файлы исходного кода имеют расширение .class. Что такое классы в терминах ООП вы уже знаете, но в Java классы - это более широкое понятие. Сама программа - это тоже класс. У классов также есть модификаторы доступа. Важно про классы - это то, что в файл с расширением джава следует класть только один класс и делать его публичным. Формально, язык не запрещает иметь в файле другие, не публичные классы, но писать так свои программы - это не толкьо дурной тон, но и весьма сбивающая с толку практика. У классов также есть правила именования. Название класса - это имя существительное в именительном падеже, написанное с заглавной буквы. Если требуется назвать класс в несколько слов, применяют так называемый upper camel case, то есть пишут слова строчными буквами, делая заглавной первую букву каждого слова.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Метод мейн - это единственный в своём роде метод, который является точкой входа в программу. Метод является публичным, и должен находиться в публичном классе, то есть он доступен для исполнения любому желающему. А желает его исполнить JVM. Метод именно с такой сигнатурой (публичный, статический, ничего не возвращающий, принимающий массив строк) - это конвенция, договорённость, об именовании. JVM при старте программы среди всех пакетов и классов будет искать именно этот метод и будет передавать ему именно массив строк в качестве параметра. При создании этого метода важно полностью повторить его сигнатуру и обязательно написать его с название со строчной буквы.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
С комментариями всё просто - это часть кода, которую игнорирует компилятор при преобразовании исходного кода. Комментарии бывают:
  \begin{itemize}
  \item \code{// comment} - до конца строки. Самый простой и самый часто используемый комментарий. Эти комментарии обычно поясняют неочевидные программные решения или сложные алгоритмы.
  \item \code{/* comment */} - внутристрочный или многострочный. Никогда не используйте его внутри строк, несмотря на то, что это возможно. Обычно эти комментарии используют, чтобы оставить какое-нибудь длинное сообщение будущим поколениям программистов, которые будут поддерживать этот код.
  \item \code{/** comment */} - комментарий-документация. Многострочный. Из него утилитой Javadoc создаётся веб-страница с комментарием. Самый полезный из всех полезных комментариев. Сейчас будем учиться делать из таких комментариев целые веб-сайты с программной документацией.
  \end{itemize}

  Есть ещё такое собирательное понятие, как ресурсы, но его, возможно не следует рассматривать прямо сейчас потому что оно не является обязательным для вообще любого проекта, в отличие от пакетов, классов и комментариев. Работу с ресурсами мы разберём когда будем беседовать о более сложных проектах.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Для дальнейших упражнений на сегодняшнем уроке нам понадобится небольшой проект, буквально из двух классов в двух пакетах, без каких-то ограничений видимости и других усложнений. На основе этого проекта мы и поговорим об оставшихся на сегодня двух несложных темах - терминальная сборка и генерация документации. Дерево проекта представлено на слайде, где папка с выходными (скомпилированными) бинарными файлами пуста, а файл README.md создан для лучшей демонстрации корня проекта.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Итак. У нас был простейший проект, написать его было элементарно, что там, простой хелловорлд, скомпилировать и запустить его также просто. Нам понадобится утилита javac из состава JDK которая скомпилирует из текста программы байт-код, и утилита java из состава JRE которая этот байт-код сможет интерпретировать. То есть очевидно, и мы просто проговорим это дополнительно, что простому пользователю для запуска программы не нужен весь тяжёлый ЖДК. Показываем работу следующими командами
\begin{verbatim}
 ls
 javac Main.java
 ls
 java Main
\end{verbatim}
Также существует забавный факт, что скомпилированные джава классы всегда содержат одинаковые первые 4 байта, которые в 16тиричном представлении формируют надпись «кофе, крошка», cafe babe.
(открыть мейн.класс в хекс-редакторе, показать)

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Для компиляции более сложных проектов, содержащих каике-то иерархические структуры из пакетов и классов, необходимо указать компилятору, откуда забирать файлы исходников (сорспас) и куда класть готовые классы (д может быть расшифрован как директория или как дестинейшн - назначение), а интерпретатору, откуда забирать файлы скомпилированных классов (класпас). Как хорошо видно среди только что написанных букв, для этого достаточно через пробел написать соответствующие ключи компиляции и запуска. Конечно, писать каждый раз эти ключи довольно утомительно и для автоматизации этого процесса придумали сборщики проектов, но всегда круто знать и уметь делать вещи в отсутствие сложного инструментария. Показываем работу следующими командами
\begin{verbatim}
javac -sourcepath ./src -d out src/ru/gb/jcore/sample/Main.java
java -classpath ./out ru.gb.jcore.sample.Main
\end{verbatim}

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
И к последней на сегодня теме, которая мочему-то вызывает у многих даже активно практикующих программистов отторжение. К самому полезному для передачи опыта между программистами и командами программистов. К документации на свой код. Конечно, особенно ярые противники описывать свою работу сейчас возмутятся, мол, я ж программист, пусть программную документацию пишут технические писатели. Но если подумать, то техпис фактически всё равно придёт к вам, программисту, за разъяснениями, что именно делает тот или иной фрагмент кода. А комментарии к коду всё равно писать, да и техпису, скорее всего придётся отвечать в текстовом виде, так почему бы не облегчить себе жизнь сразу, документируя свой код по мере написания, например, между спринтами. 

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Чтобы просто создать документацию надо вызвать утилиту javadoc с небольшим количеством ключей, давайте их разберём. Уже знакомый нам ключ -d означающий папку (или директорию, кому как больше нравится) в которую следует положить готовую документацию. Помним, ключ легко запомнить, если расшифровать его как дестинейшн, назначение. -sourcepath означает папку, где лежат исходники проекта, как мы помним, в исходниках мы пишем те самые комментарии, которые потом можно преобразовать в джавадок. -cp говорит о том, где лежат готовые скомпилированные классы, эта информация нужна, чтобы понять, как программа в итоге скомпилировалась, что в ней задействовано, что как связано и прочее. -subpackages говорит о том, что надо взять не только указанный далее пакет, но и все его подпакеты рекурсивно. Ну и, собственно, пакет, для которого нужно создать документацию, ru. Показываем работу следующими командами:
\begin{verbatim}
javadoc -d docs -sourcepath src -cp out -subpackages ru
\end{verbatim}
Если нужно сгенерировать документацию к конкретному пакету, например, если вы хотите разложить их по разным папкам, то надо указатеь его полный адрес, и, вероятно, убрать ключ subpackages

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
Чтобы учесть то, что происходитс ОС Windows надо чуть больше, поскольку так исторически сложилось, что у Windows есть проблемки с локалью. Поскольку все программы на Java пишутя в кодировке UTF-8, а основная кодировка всех приложений, работающих под ОС виндоус это ср1251, то при создании документации стандартными средствами итоговые веб-страницы создаются на клингонском. Чтобы перевести их на земной кириллический, нужно добавить три ключа - указать какая локаль установлена -locale, в какой кодировке исходный текст  -encoding utf-8, в какой кодировке должен быть итоговый документ  -docencoding cp1251. Показываем работу следующими командами:
\begin{verbatim}
javadoc -locale ru_RU -encoding utf-8 -docencoding cp1251 \
 -d docs -sourcepath src -cp out -subpackages ru
\end{verbatim}
Поскольку я сейчас не с виндоусом, то такие настройки наоборот, сломают отображение.

% -----------------------------------------------------------------------------------
\showslide{build/jc-1-b.pdf}
На этом уроке мы рассмотрели историю и причины создания языка, его окружение и структуру проекта, узнали, что скрывают в себе такие аббревиатуры как JDK JRE JVM SDK JIT CLI. Рассмотрели базовое применение утилит java, javac и javadoc. В качестве домашнего задания попробуйте
\begin{itemize}
\item Создать проект из трёх классов (основной с точкой входа и два класса в другом пакете), которые вместе должны составлять одну программу, позволяющую производить четыре основных математических действия и осуществлять форматированный вывод результатов пользователю. 
\item Скомпилировать проект, а также создать для этого проекта стандартную веб-страницу с документацией ко всем пакетам.
\end{itemize}

На следующей лекции мы поговорим о том как осуществлять управление более сложными проектами: Jar-файлы; сборщики Gradle/Maven; чтоб такое репозитории и как ими пользоваться.

\end{document}