Documentation Comments. If you do it in PL/SQL, why not in OAF?

Talks About: Providing java documentation of your OAF work to clients.


Its a big surprise that usually OAF development items are missing proper documentation.

Basically OAF is a java framework and java provide very nice documentation approaches. There is a java utility called javadoc, which can automatically generate html based documentation from the source code files. All the OAF documentation for API's which you see are not hand written seperately, but automatically generated from source code. You can also create such documentation(for whole project) and give it to your client.

Impressive?. After all, its a quality aspect of what is being delivered.

How it works?

So far you have been using comments in java. Now you use documentation comments.

Documentation comment is nothing new but about same thing.What's needed is to only place these comments at right place in right way,and a bit of knowledge of  few javadoc tags.

Where to write?

Write your documentation comments ahead of declaration of class, methods,fields, constructor etc.

How to write?

A documentation comment is written between the /** and */ characters. Here is  a sample.

/**

*This is a java documenatation comment written ahead of a class,method etc.

*Write as long as description you want.

*/

 

Now, how about getting return type, parameters etc. in documentation , like this

 

Well, just specify the javadoc tags in your comments and done. Javadoc tags starts with '@'.

/**

*Returns the middle-tier Application Module associated with the given web bean. This is a 

*convience method that delegates to OAWebBeanHelper. If neither AM Definition nor AM 

*InstanceOA Extension property was specified for the web bean, then the paranet web beans 

*will be examined and the application *module instance in the closest parent web bean will 

*be returned.

*@param webBean - The webBean which contains the ApplicationModule reference.

 */

Let's take an step step example about how to do it in JDeveloper.


1. Select your file in JDeveloper. I choose DebugSearchCO.java.



2. I have a method called searchEmployeeName, for which I want to provide java documentation. Right click this method in Structure pane and select "Add Javadoc comments".



3. This brings you to code editor, with @param and @return tag already available. We just need to write descriptions.


4. Write the description of what this method does, details of parameters, return values.


5. Go to Run-> Javadoc <FileName>. In my case Javadoc DebugSearchCO.java



6. See the log window and click "View Documentation".



7. See the your class name and click it. In my case DebugSearchCO. Here is the result. 




8. In similar way, you can provide documentation comments for other methods, variables and class itself. Here is a brief list of javadoc tags which we can use.(Taken from wikipedia). Please do a search about how to use them.


Apart from a single java file, we can generate javadoc for whole project also. Just select the project and generate javadoc for it.

 
 
Contact me at :  This email address is being protected from spambots. You need JavaScript enabled to view it.

Add comment


Security code
Refresh

Comments  

 
# RE: Documentation Comments. If you do it in PL/SQL, why not in OAF?Guest 2014-04-07 08:09
This comment has been deleted by Administrator
 
 
0 # iWiDi - Documentation Comments. If you do it in PL/SQL, why not in OAF?Anemonalove 2017-07-18 09:26
Hello guys! Who wants to see me live? I have profile at HotBabesCams.co m, we can chat,
you can watch me live for free, my nickname is Anemonalove , here is my pic:

Reply | Reply with quote | Quote