В настоящее время я занимаюсь классом AP Java, и я даже не могу понять, что такое «javadoc», все, что я, кажется, вынимаю до сих пор, это его «другой» способ комментирования при создании API так программист может лучше прочитать код. , ,Что такое javadoc?
Я новичок в этом, и я был бы признателен за любую начальную точку, чтобы я мог, по крайней мере, воспользоваться этой концепцией.
Javadoc - это программа, которая считывает ваши java-файлы и создает из них HTML-документацию. Вы используете его, добавляя комментарии к документации, а затем вызываете ее.
Javadoc - это программа, подобная компилятору, который читает ваши коды и выгружает определенные части, чтобы создать (очень очень очень) полезную документацию в виде html-страниц. Страницы API, которые вы используете для стандартного кода Java, создаются с использованием Javadoc.
При анализе кода Javadocs ищет две вещи: структуру кода и комментарии Javadoc. Структура кода - это только сам код. Это используется для создания базовой структуры страницы (например, имя класса, поля, методы и т. Д.). Комментарии Javadoc - это специальные комментарии, которые начинаются с /** вместо обычного /* Что касается обычного java-компилятора, это не имеет никакого значения. Однажды в комментарии Javadoc вы пишете о конкретном аспекте кода, на который вы ссылаетесь, и можете использовать теги html, а также какой-либо другой специальный синтаксис. Вы можете узнать больше об этом here
Я думал о том, как описать это, но если честно, я думаю, что SO Javadoc тег делает очень хорошую работу:
Javadoc является расширяемой документацией поколения системы, которая считывает специально отформатированные комментарии в исходном коде Java и генерирует скомпилированную документацию. Он обычно используется для создания документации API в виде веб-страниц HTML.
Многие IDE также используют Javadocs для генерации контекстных описаний API. Javadocs может сделать разницу между крайне неясной библиотекой и тем, что приятно использовать.
Javadocs, используйте их!
«генерирует скомпилированную документацию», что я не понимаю. , , где именно он их генерирует? , , , он просто делает простой html-документ или как-то отображается в вашей среде IDE? –
@someone Результат - это просто HTML, ничего особенного. Но большинство IDE имеют возможность анализировать их и отображать их в среде IDE (т. Е. При поиске методов он может отображать JavaDoc для этого метода), некоторые также анализируют JavaDoc из исходного кода. .. – MadProgrammer
@ someone; посмотрите на это: http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#runningjavadoc –
ВС определяет JavaDoc следующим образом (http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html):
Javadoc is a tool for generating API documentation in HTML format
from doc comments in source code
Комментарии имеют определенный формат, который стал широко известен как "Javadoc". Вы можете увидеть более подробную информацию по адресу: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Всякий раз, когда вам нужно искать метод Java, вы используете имя метода и обратитесь к документации, чтобы узнать, что он делает. Большой !
Но как эти документы появились? Как было создано столько документации? Был ли кто-то нанят для этого?
Ну, когда вы пишете код, вам нужно правильно объяснить его в исходных файлах, используя комментарии. /** */ отмечает блок комментариев. Теперь javadoc отвечает за разбор этих комментариев в документации (это делает HTML-файлы из этих комментариев). Таким образом, никто не был нанят только javadoc был выполнен.
Вот пример начинающегося комментарий:
/**
* Classname
* Version info
* Copyright notice
*/
Но это еще не все. javadoc очень мощный. Это позволяет вам даже писать базовый HTML внутри комментариев, а затем анализирует HTML, чтобы получить правильный вывод. /** <html> */ Вот почему некоторые страницы JacaDoc имеют таблицы. Они были сделаны с использованием <td> и <tr> тегов в HTML
Например,
/**
* First paragraph.
* <p><ul>
* <li>the first item
* <li>the second item
* <li>the third item
* <ul><p>
* Second paragraph.
*/
Если вы хотите Javadoc правильно работать с вашим кодом, следовать Конвенции кода Java: http://www.oracle.com/technetwork/java/codeconventions-150003.pdf если ваш код придерживается конвенции , для javadoc становится легко сделать документацию.
Вот официальное Oracle руководство по написанию комментариев документации: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Это хорошее начало, я думаю, что JavaDoc - это термин, используемый для описания 1- инструмента для генерации документации; 2 - Соглашения, за которыми следует этот инструмент; 3- Результат, созданный этим инструментом ... или что-то в этом роде ...что должно сделать его лучшим ответом;) – MadProgrammer
@MadProgrammer Посмотрите на редактирование. –
JavaDoc является удивительным. Да, это способ прокомментировать ваш код, но вы можете использовать инструмент JavaDoc для создания документации API, такой как [this] (http://docs.oracle.com/javase/7/docs/api/), которая предоставляет (разумным) стандартным документом через несколько API. Многие IDE также используют его для отображения всплывающих подсказок и расширенной помощи во время кодирования ... – MadProgrammer
@MadProgrammer * «JavaDoc - это потрясающе». * Это +1. Мне надоело ждать, пока Netbeans не найдет JDocs из сети («должен выяснить, как настроить его, чтобы получить их с локальной машины»), и просто добавьте эту ссылку в свой комментарий (к основным документам), постоянно открывающийся на вкладке 2 'из FF (' tab 1 '- GMail). –
@AndrewThompson Я думаю, что если вы можете скачать JavaDocs в виде zip-файла, вы можете перейти в Инструменты -> Платформы Java, выбрать версию Java, перейти на вкладку «JavaDoc» и добавить ссылку на zip-файл ... Я могу немного что-то сделать;) – MadProgrammer