aspose file tools*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Pls Help ( javadoc comment for DataAccessFactory) Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Soft Skills this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Pls Help ( javadoc comment for DataAccessFactory)" Watch "Pls Help ( javadoc comment for DataAccessFactory)" New topic
Author

Pls Help ( javadoc comment for DataAccessFactory)

Amit Kr Kumar
Ranch Hand

Joined: Feb 08, 2002
Posts: 100
Hi Mark
javadoc comment for DataAccessFactory
----------------------------------------
My design is somewhat similar to your design where i have a FBNDataAccessFactory which has getDataAccess(dns,port) and getDataAccess(locladb) method for getting data access in local or network mode.
Now the problem is how to put javadoc comment for the class becoz being a connection factory it is returning a connection to remote data server and in local mode it is returning a connection to database and not server.
Problem is of connection to data server or local database
Amit
[ June 25, 2002: Message edited by: Amit Kr Kumar ]
[ June 25, 2002: Message edited by: Amit Kr Kumar ]
[ June 25, 2002: Message edited by: Mark Spritzler ]
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17260
    
    6

Here's my javadoc for the class portion of my Factory

Then each method has it's own.
Here's my javadoc for Remote mode method

Here's my local method javadoc


Hope that helps. And don't copy it word for word.
Mark


Perfect World Programming, LLC - Two Laptop Bag - Tube Organizer
How to Ask Questions the Smart Way FAQ
John Smith
Ranch Hand

Joined: Oct 08, 2001
Posts: 2937

* @param String host - the server host URL.

Mark,
I see that you are using the
@param <Type> <param> - <description>
format instead of
@param <param> <description>
In one of the recent posts here, someone pinted out that this is wrong. You don't need a dash either, -- it will be generated. Any reasons that you've used your javadoc format?
Eugene.
Mike Piotrowski
Ranch Hand

Joined: Apr 24, 2002
Posts: 82
I elected to use the latter appraoch
@param <param> <description>
. It confused me which format to use, considering the original files seem to use both. I just picked one and stayed consistent with it throughout.
Both ways seemed to work fine for when I generated the javadocs, and didn't think either way would have a big impact on my score.
Mike
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17260
    
    6

Actually I thought I had just copied and pasted from their code and used the same standard.
Also if you don't include the type then the type didn't show up in the Javadoc, and if you look in the Java Api Javadocs they all have type in the html pages.
I got 20/20 on docs, so my guess is either way will work fine.
Mark
John Smith
Ranch Hand

Joined: Oct 08, 2001
Posts: 2937
Mar wrote:

.. and if you look in the Java Api Javadocs they all have type in the html pages.

Actually, Java Api Javadocs don't have type. Here is a typical example from JDK 1.3.1:
The following SUN source in String.java (notice that there are no types or dashes:

Eugene.
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17260
    
    6

You just posted a constructor, they don't have return values. If you look at an actual method that returns a value you will see it.
Let's also say that without it, I never got the return values to show up in my Javadocs. But when I put it in there it did show.
Mark
Mark Spritzler
ranger
Sheriff

Joined: Feb 05, 2001
Posts: 17260
    
    6

And this is taken directly from the DataInfo class that Sun provides

As far as the dash, I don't think those are necessary.
Mark
 
 
subject: Pls Help ( javadoc comment for DataAccessFactory)