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

Я сделал пакет еще в 2005 году. Я посмотрю, смогу ли я его откопать. Задокументировали ли вы все свои классы и методы хотя бы для одного класса? В конечном итоге вы получите набор html-файлов на основе ваших .java-файлов. Кроме того, узнайте о файле манифеста Java. Это очень важно.

Entree 13.04.2023 04:16

Эта инструкция очень важна. «Чтобы сделать класс частью пакета, вы должны включить оператор пакета в качестве первого оператора в исходный файл».

Entree 13.04.2023 04:31

Файлы должны иметь ту же структуру, что и полные имена пакетов. Таким образом, у вас должна быть папка с именем my_proj, еще одна для бета-версии в myproj, еще одна для дельты в my_proj и так далее.

Entree 13.04.2023 04:33

@MacGyver Спасибо за своевременный ответ на мой вопрос. Я хорошо знаю, как создавать классы в пакетах, и знаю о вложенных пакетах. Мой вопрос касается документирования всего проекта, состоящего из трех разных пакетов. Я хочу, чтобы документация верхнего уровня описывала весь проект.

Andrew S 13.04.2023 04:39

Я не знаю, что «проект» является реальной сущностью (или термином) Java. Скорее всего, это термин, используемый вашей IDE. Чтобы подтвердить, вы можете отследить исходный код для javadoc. Какую IDE вы используете? Java и Javadoc, вероятно, были разработаны задолго до того, как современные интегрированные среды разработки позволяют создавать проекты Java.

Entree 13.04.2023 04:44

Это скорее общий вопрос, независимо от какой-либо конкретной IDE. Думаю, я использую термин проект для определения набора связанных пакетов и файлов классов, которые работают вместе для определения программного приложения при компиляции. Это не что иное, как это.

Andrew S 13.04.2023 04:48

Ответ на ваш вопрос, скорее всего, невозможен «из коробки», если для него нет расширения кода Visual Studio (их тысячи). Или пакет nuget для Visual Studio. Visual Studio начала использовать термин «проект» для компьютерных приложений, и за ним последовали все IDE. Я уверен, что Microsoft была не первой, кто использовал этот термин для группировки набора файлов исходного кода и других объектов в единую сущность. Одна вещь, которую нужно проверить, — это IDE, которые работают исключительно с Java. Возможно, они построили расширение для него. Затмение — обычное дело. Джетбрейнс, может быть.

Entree 13.04.2023 04:52

Могу я задать вам простой вопрос здесь? Вы спрашиваете, чтобы вы могли легко документировать изменения версии проекта на верхнем уровне? А когда кто-то переходит на конкретную версию, он видит сводку (изменения, которые произошли с момента последней версии)?

Entree 13.04.2023 05:26

Я хочу сказать, как называется проект, чем он занимается, почему он существует. кто его авторы и какова текущая версия.

Andrew S 13.04.2023 05:36

Причина, по которой я спрашиваю, заключается в том, что программисты в конечном итоге проводят различие между созданием приложения (проекта в IDE) и созданием среды программирования или API (в Java это называется пакетом, в C# это будет DLL или библиотека, в Python , это будет модуль и т. д.). Если вы действительно создаете приложение, вам не следует брать файлы из пакета. Вы должны включить пакет и вызвать в него. Причина, по которой проект существует, состоит в том, чтобы разделить идею проекта (для приложения) и вещи, которые нужно включить в проект (например, пакеты). Наверно поэтому его нет.

Entree 13.04.2023 05:38

Извини, я не могу помочь тебе, приятель. Я думаю, что большинство программистов помещают эту информацию о проекте верхнего уровня в систему управления версиями (например, SVN, GitHub и т. д.) для приложения или проекта. Всякий раз, когда вы делаете коммит в Github, вы можете перечислить, какие файлы нужно изменить для этой версии, и поместить туда документацию. То, что вы задаете, является интересным и сложным вопросом, поэтому его может еще не быть.

Entree 13.04.2023 05:43

У меня может быть реальный ответ для вас или, по крайней мере, зацепка. Javadoc позволяет вам создать "стандартный доклет". Вы даже можете настроить доклет в своем собственном формате! Я думаю, это то, что вы хотите. Автор может пойти туда. И другие нестандартные вещи.

Entree 13.04.2023 06:04

«Чтобы настроить вывод инструмента Javadoc, вам нужно написать собственный доклет, который определяет содержимое и формат вывода, который вы хотите. Если вы хотите, чтобы вывод HTML был примерно в том же формате, что и вывод по умолчанию, вы можете использовать стандартный doclet в качестве отправной точки для создания вашего doclet».

Entree 13.04.2023 06:06

Хотя часто делается так, чтобы в пакете был только один уровень папки, в учебнике по Java часто рекомендуется начинать с папки пакета «com» ​​или «net», а затем другую папку вниз, а затем внутри этой секунды запускать отдельные наборы папок пакетов с либо папки подмножества, либо классы. Веб-серверы становятся ужасно суетливыми, если эта схема именования не найдена в пакетах jar.

Samuel Marchant 13.04.2023 06:07

Это поможет вам начать. Просто не забудьте посмотреть версию Java, которую вы установили. docs.oracle.com/javase/7/docs/technotes/guides/javadoc/docle‌​t/…

Entree 13.04.2023 09:07

Кроме того, вы можете опубликовать вопрос здесь, как только вы начнете. Найдите существующие вопросы для «пользовательского доклета». forums.oracle.com/ords/apexds/domain/dev-community/category/‌​…

Entree 13.04.2023 09:08

Сэмюэл Марчент, спасибо, это как раз то, что мне было нужно.

Andrew S 16.04.2023 20:43
Пользовательский скаляр GraphQL
Пользовательский скаляр GraphQL
Листовые узлы системы типов GraphQL называются скалярами. Достигнув скалярного типа, невозможно спуститься дальше по иерархии типов. Скалярный тип...
Как вычислять биты и понимать побитовые операторы в Java - объяснение с примерами
Как вычислять биты и понимать побитовые операторы в Java - объяснение с примерами
В компьютерном программировании биты играют важнейшую роль в представлении и манипулировании данными на двоичном уровне. Побитовые операции...
Поднятие тревоги для долго выполняющихся методов в Spring Boot
Поднятие тревоги для долго выполняющихся методов в Spring Boot
Приходилось ли вам сталкиваться с требованиями, в которых вас могли попросить поднять тревогу или выдать ошибку, когда метод Java занимает больше...
Полный курс Java для разработчиков веб-сайтов и приложений
Полный курс Java для разработчиков веб-сайтов и приложений
Получите сертификат Java Web и Application Developer, используя наш курс.
2
18
52
1
Перейти к ответу Данный вопрос помечен как решенный

Ответы 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, если кто-нибудь подтвердит, что я хотел бы знать.

Другие вопросы по теме