Guide to Prepare Java Documentation
The Place of Documentation in Popular Culture
You must have heard many things like “Wow, I wouldn’t touch any undocumented code!” or “Undocumented project has no difference from a valley with no map.” Today, we will learn how to prepare a guide on how we code.
What is Documentation ?
To briefly explain, documentation is the part where we explain every single particle’s (Method, Class, Field, Return Type, Exception, etc.) meaning, how they work, and why we have them.
Its importance is too great to underestimate. For example, sometimes you may forget or not understand what that Method does after months of not looking. But with the help of documentation, you can remember the meaning of it and solve your problems. Another scenario is that you may leave the project and replace your position with another developer. It is a binding duty as a colleague for you to lead the way for him.
The image you see below is an example of Doc.
What Are the Parts of Documentation ?
Description: The Method’s main explanation and the function get explained in this part. You need to explain what the Method does and how it does it.
Param: It is the parameter part. In this part, you need to write the types of parameters and their function used in the Method.
Throws: If there is a scenario where you throw an exception, you should specify it here. You can see a clear example of “throwing an exception if the app doesn’t start” in the example above.
Return: The part where the Method gets specified on which data type and which data will return.
See: If the Method has an overloading version, it should be specified here. We can say that it has a meaning like “I wrote this one, but you can check other types of it written with different parameters.”
Knowing this many parameters would be enough for the basic level.
How to Create a Java Documentation ?
It is so simple! You can create a draft by hovering over the Method you have written and pressing the Enter key after the “ /** ” characters.
CONGRATULATIONS! You will no longer say, “What was this code doing?”, “Why did I write this?”.
If this much hasn’t been enough for you, I shall invite you to my JAVA DOC HTML RENDER themed article.
Good work, everyone.
