JavaDoc, документация верхнего уровня для проекта в целом
Я думал, что предоставление верхнего уровня (уровень проекта) Java Doc будет простым делом, но я оглядываюсь и вижу изобилие информации о том, как документировать пакеты, но ничего о том, как документировать целые проекты Java, так что главная страница документации содержит заголовок и описание проекта, а также все пакеты в проекте.
Допустим, у меня есть проект, в его каталоге src у меня есть три пакета, каждый с различными классами Java. Каждый класс имеет JavaDoc, а каждый пакет альфа, бета и дельта имеет внутренний package-info.java для документирования каждого пакета: Как показано ниже. Когда я делаю это, указатель документации не имеет названия и просто перечисляет пакеты. Я хотел бы, чтобы место включало название и описание проекта, информацию о версии и т. д.
src:
======================
alpha
package-info.Java
Theta.Java
Omega.Java
beta
package-info.Java
Gamma.java
Epsilon.Java
delta
package-info.java
Kappa.java
Iota.java
Есть ли способ иметь документацию Java верхнего уровня для всех трех пакетов, не помещая все три пакета в самый внешний пакет? Или самый внешний пакет - единственный способ сделать это, и как Java ожидает, что проект будет структурирован? Например:
src:
======================
my_proj:
package-info.Java
my_proj.alpha
package-info.Java
Theta.Java
Omega.Java
my_proj.beta
package-info.Java
Gamma.java
Epsilon.Java
my_proj.delta
package-info.java
Kappa.java
Iota.java
Эта инструкция очень важна. «Чтобы сделать класс частью пакета, вы должны включить оператор пакета в качестве первого оператора в исходный файл».
Файлы должны иметь ту же структуру, что и полные имена пакетов. Таким образом, у вас должна быть папка с именем my_proj, еще одна для бета-версии в myproj, еще одна для дельты в my_proj и так далее.
@MacGyver Спасибо за своевременный ответ на мой вопрос. Я хорошо знаю, как создавать классы в пакетах, и знаю о вложенных пакетах. Мой вопрос касается документирования всего проекта, состоящего из трех разных пакетов. Я хочу, чтобы документация верхнего уровня описывала весь проект.
Я не знаю, что «проект» является реальной сущностью (или термином) Java. Скорее всего, это термин, используемый вашей IDE. Чтобы подтвердить, вы можете отследить исходный код для javadoc. Какую IDE вы используете? Java и Javadoc, вероятно, были разработаны задолго до того, как современные интегрированные среды разработки позволяют создавать проекты Java.
Это скорее общий вопрос, независимо от какой-либо конкретной IDE. Думаю, я использую термин проект для определения набора связанных пакетов и файлов классов, которые работают вместе для определения программного приложения при компиляции. Это не что иное, как это.
Ответ на ваш вопрос, скорее всего, невозможен «из коробки», если для него нет расширения кода Visual Studio (их тысячи). Или пакет nuget для Visual Studio. Visual Studio начала использовать термин «проект» для компьютерных приложений, и за ним последовали все IDE. Я уверен, что Microsoft была не первой, кто использовал этот термин для группировки набора файлов исходного кода и других объектов в единую сущность. Одна вещь, которую нужно проверить, — это IDE, которые работают исключительно с Java. Возможно, они построили расширение для него. Затмение — обычное дело. Джетбрейнс, может быть.
Могу я задать вам простой вопрос здесь? Вы спрашиваете, чтобы вы могли легко документировать изменения версии проекта на верхнем уровне? А когда кто-то переходит на конкретную версию, он видит сводку (изменения, которые произошли с момента последней версии)?
Я хочу сказать, как называется проект, чем он занимается, почему он существует. кто его авторы и какова текущая версия.
Причина, по которой я спрашиваю, заключается в том, что программисты в конечном итоге проводят различие между созданием приложения (проекта в IDE) и созданием среды программирования или API (в Java это называется пакетом, в C# это будет DLL или библиотека, в Python , это будет модуль и т. д.). Если вы действительно создаете приложение, вам не следует брать файлы из пакета. Вы должны включить пакет и вызвать в него. Причина, по которой проект существует, состоит в том, чтобы разделить идею проекта (для приложения) и вещи, которые нужно включить в проект (например, пакеты). Наверно поэтому его нет.
Извини, я не могу помочь тебе, приятель. Я думаю, что большинство программистов помещают эту информацию о проекте верхнего уровня в систему управления версиями (например, SVN, GitHub и т. д.) для приложения или проекта. Всякий раз, когда вы делаете коммит в Github, вы можете перечислить, какие файлы нужно изменить для этой версии, и поместить туда документацию. То, что вы задаете, является интересным и сложным вопросом, поэтому его может еще не быть.
У меня может быть реальный ответ для вас или, по крайней мере, зацепка. Javadoc позволяет вам создать "стандартный доклет". Вы даже можете настроить доклет в своем собственном формате! Я думаю, это то, что вы хотите. Автор может пойти туда. И другие нестандартные вещи.
«Чтобы настроить вывод инструмента Javadoc, вам нужно написать собственный доклет, который определяет содержимое и формат вывода, который вы хотите. Если вы хотите, чтобы вывод HTML был примерно в том же формате, что и вывод по умолчанию, вы можете использовать стандартный doclet в качестве отправной точки для создания вашего doclet».
Хотя часто делается так, чтобы в пакете был только один уровень папки, в учебнике по Java часто рекомендуется начинать с папки пакета «com» или «net», а затем другую папку вниз, а затем внутри этой секунды запускать отдельные наборы папок пакетов с либо папки подмножества, либо классы. Веб-серверы становятся ужасно суетливыми, если эта схема именования не найдена в пакетах jar.
Это поможет вам начать. Просто не забудьте посмотреть версию Java, которую вы установили. docs.oracle.com/javase/7/docs/technotes/guides/javadoc/doclet/…
Кроме того, вы можете опубликовать вопрос здесь, как только вы начнете. Найдите существующие вопросы для «пользовательского доклета». forums.oracle.com/ords/apexds/domain/dev-community/category/…
Сэмюэл Марчент, спасибо, это как раз то, что мне было нужно.
Ответы 1
Прошло несколько дней с тех пор, как я опубликовал вопрос, и я разработал то, что, по моему мнению, является правильным способом сделать это в Java 1.9 и выше. Для версий Java <= 1.8 и ниже у меня до сих пор нет ответа, и буду рад предложениям.
Во-первых, по соглашению сами проекты должны находиться в именованном пакете. По соглашению это выглядит как URL-адрес в обратном порядке, начиная с наименее конкретной вещи и переходя к наиболее конкретному имени проекта. Например:
edu.myuni.mycourse.myname.my_proj2000
или для коммерческой организации.
com.mycompany.myproj2000
То, что вы увидите в своем каталоге проекта, если вы создадите такое имя пакета, — это иерархия папок, такая как следующая. Это то, что сгенерирует IDE, но если вы делаете это вручную (без и IDE), вам придется создавать это самостоятельно.
src/com/mycompany/myproj200/
Таким образом, пакеты вашего проекта будут созданы внутри каталога myproj2000, как показано ниже. Если мы возьмем класс Java, такой как Theta, то так и будет. com.mycompany.myproj2000/alpha/Theta.java. Это так называемое полное имя. Преимущество этого заключается в уникальной идентификации вашего класса в большом проекте, где классы в разных пакетах могут иметь одно и то же имя.
Таким образом, структура каталогов выглядит следующим образом: каждый пакет получает package-info.java для целей документирования, а проект в целом получает module-info.java. Ниже приведена структура проекта, а ниже приведен пример того, что package-info.java и module-info.java будут выглядеть так.
src:
======================
com.mycompany.myproj2000:
module-info.java
com.mycompany.myproj2000.alpha
package-info.Java
Theta.Java
Omega.Java
com.mycompany.myproj2000.beta
package-info.Java
Gamma.java
Epsilon.Java
com.mycompany.myproj2000.delta
package-info.java
Kappa.java
Iota.java
Тогда в этом проекте информация о пакете выглядит следующим образом, где документация находится над документацией пакета.
/**
*My documentation for my lovely alpha package, blah blah blah. It does blah blah.
* @Author Joe Bloggs
* @Version 1.02 Spring 2023
**/
package com.mucompany.myproj2000.apha;
Модуль-info.java выглядит аналогично.
/**
* This project does blah blah blah it was created for blah blah so that blah blah
* @Author Joe Bloggs
* @Version 1.02 Spring 2023
**/
module com.mycompany.myproj2000{
}
Я подозреваю, что до Java 1.9, когда были введены модули, самый внешний пакет com.mycompany.myproj2000 также получил package-info.java, если кто-нибудь подтвердит, что я хотел бы знать.
Я сделал пакет еще в 2005 году. Я посмотрю, смогу ли я его откопать. Задокументировали ли вы все свои классы и методы хотя бы для одного класса? В конечном итоге вы получите набор html-файлов на основе ваших .java-файлов. Кроме того, узнайте о файле манифеста Java. Это очень важно.