0
Guys, I’m researching documentation at Kotlin. Effectively how to carry out the documentation of a particular app, I noticed that it is spoken in Kdoc, but only find Javadoc in version 3.0 of Android Studio. I also saw something about Dokka, but it was not clear to me how the documentation works. Can anyone tell me, how it is in practice , and what is official regarding documentation in Kotlin?
3
Javadoc is a very similar program to a compiler that reads your code and extracts certain parts from it to create very useful documentation in the form of HTML pages. The API pages you use for standard java code are made using Javadoc.
When analyzing your code, Javadoc looks for two things: code structure and Javadoc comments. The code structure is just the code itself. This is used to build the basic structure of a page (i.e., class name, fields, methods, etc.). Javadoc comments are special comments starting with /** instead of the usual /* (with regard to the normal java compiler, this makes no difference). Once in a Javadoc comment, you write about the specific aspect of the code you are referencing and can use HTML tags as well as other special syntax.
Whenever you need to search for a Java method, Google the method name and see the documentation to see what it does. Great !
But how were these documentations created? How was so much documentation generated? Someone was hired to do this?
Well, whenever you write a code, it is necessary to explain it properly in the source files using comments. /** */ marks a comment pad. Now, the javadoc is responsible for analyzing these comments in the documentation (creates HTML files from these comments). Therefore, no one was hired, only the javadoc was executed.
Here’s an example of an initial comment:
/**
* Nome da classe
* Informação da versão
* Nota de direitos autorais
*/
But that’s not all. javadoc is very powerful. It allows you to write basic HTML inside the comments and parses HTML to get a proper output. /** <html> */ That’s why some Javadoc pages have tables. They were made using the tags <td> and <tr> in HTML.
For example,
/**
* Primeiro parágrafo.
* <p> <ul>
* <li> o primeiro item
* <li> o segundo item
* <li> o terceiro item
* <ul> <p>
* Segundo parágrafo.
*/
If you want javadoc to work correctly with your code, follow the Java Code Convention: http://www.oracle.com/technetwork/java/codeconventions-150003.pdf if the code adheres to the convention, it will be easy for javadoc to do the documentation.
Here is the official Oracle guide for writing documentation comments: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
Javadoc is an extensible documentation generation system that reads comments specially formatted in Java source code and generates compiled documentation. Generally, it is used to produce documentation API in the form of HTML web pages.
The language used to document the Kotlin code (the Java Javadoc equivalent) is called Kdoc. At its core, Kdoc combines Javadoc syntax to block tags (extended to support Kotlin-specific constructs) and Markdown for comment markup.
Kotlin’s documentation generation tool is called Dokka.
Dokka has plugins for Gradle, Maven and Ant, so you can integrate documentation generation into your build process.
Just like in Javadoc, Kdoc comments start with /** and end with */. Each line of the comment can start with an asterisk, which is not considered part of the content of the comment.
By convention, the first paragraph of the documentation text is the summary description of the element, and the following text is the detailed description.
Each block tag starts in a new row and starts with the character @.
Here is an example of a documented class using Kdoc:
/**
* A group of *members*.
*
* This class has no useful logic; it's just a documentation example.
*
* @param T the type of a member in this group.
* @property name the name of this group.
* @constructor Creates an empty group.
*/
class Group<T>(val name: String) {
/**
* Adds a [member] to this group.
* @return the new size of the group.
*/
fun add(member: T): Int { ... }
}
https://kotlinlang.org/docs/reference/kotlin-doc.html
https://docs.oracle.com/en/java/javase/11/docs/specs/doc-comment-spec.html
https://www.devmedia.com.br/javadoc-implementando-documentacao-atraves-do-netbeans/2495
https://medium.com/@julesrosser/auto-generate-Kotlin-android-Documentation-with-Dokka-382248c03283
https://github.com/Kotlin/dokka
https://stackoverflow.com/questions/19172015/what-exactly-is-javadoc
Browser other questions tagged kotlin documentation
You are not signed in. Login or sign up in order to post.