Javadoc examples: Comments and usage in Eclipse

 IT, Java  Kommentare deaktiviert für Javadoc examples: Comments and usage in Eclipse
Jul 052014
 

Javadoc for java Packages

It is also possible to add a comment / short description of a package. This can be done using a file called package-info.jave inside the package. When using eclipse, you can check the option „Create package-info.java“:

Create package-info.java

Create package-info.java

Change the default comment to something like this. Important: Use only one sentence and don’t forget the point at the end.

Change comment to something like this

Change comment to something like this

This will result in:

Package description

Package description

 

Using Javadoc for classes

To describe classes, you should start with a single sentence at the beginning. This sentence is used on the overview page of a package where all classes are listed (with a short description which is this sentence). Dont forget the point at the end.

The next paragraph contains a more detailed description that will be shown on the detail page of the class. Here you can use some html tags. In this case I used a list. After that you can add some javadoc parameter.

package com.pbo.Game;

/**
 * This Class represents the main class of the F1 Betting Game.
 * <p>
 * This Class handles all the database connection stuff, it creates the GUI
 * and it contains all the rules. See method: displayRules.
 * <br>
 * It also Starts the database connection, create instances of users and rankings and so on.
 * <ul>
 * 		<li>You can also</li>
 * 		<li>use a list</li>
 * 		<li>here in the description of the class</li>
 * </ul>
 * 
 * @author philipp
 * @version 0.1
 */
public class GameStarter {
    // your class here
}

Result of that comment:

Package Overview shows all classes with a short description

Package Overview shows all classes with a short description

 

Overview of one class

Overview of one class

 

Javadoc for methods

To describe methods you should begin with a short description in a single sentence. This sentence will be displayed in the method-overview of the class. After that sentence you should describe your method more detailed. This will be the description of the method. There you can use html-tags like linebreak <br> , lists <ul> , <li>, and more. You can create paragraphs by using the <p> tag. See the example below:

/**
 * This method displays all the rules for the game.
 * <p>
 * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
 * eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
 * voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
 * clita kasd. <br>
 * Nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
 * sed diam voluptua.
 * <p>
 * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
 * eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
 * voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet
 * clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit.
 * <p>
 * Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
 * eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
 * voluptua dolor sit amet.
 * <ul>
 * <li>Rule 1 ...</li>
 * <li>Rule 2 ...</li>
 * <li>Rule 3 ...</li>
 * </ul>
 * 
 * @param userName
 *            The username of the Player
 * 
 * @param difficulty
 *            The difficulty of the game, from 1 to 10, where 1 is simple
 *            and 10 means strong
 * @return the status code after the game has finished. 1=won, 2=lost
 */
public int displayRules(String userName, int difficulty) {
	// your code goes here
	return 2;
}

Results in:

Javadoc Method Overview

Javadoc Method Overview

and:

Javadoc Method Details

Javadoc Method Details

 

Using javadoc ant task

 IT, Java  Kommentare deaktiviert für Using javadoc ant task
Jul 052014
 

Javadoc is a very powerful and helpful tool of java. You can document your source, as well as insert installation or configuration information. The usage of javadoc in ant is very comfortable, setup once, use every build.
Here is an example of a simple javadoc ant task:

<target name="createJavadoc">
	<!-- this classpath is only necessary when using 3rd party libs or annotation processing -->
	<path id="annotations.classpath">
		<fileset dir=".">
			<include name="lib/**/*.jar" />
		</fileset>
	</path>
	
	<!-- creata javaDoc for package com.pbo.* inside src folder. Store javadoc in folder javaDoc -->
	<javadoc packagenames="com.pbo.*" 
		sourcepath="src" 
		defaultexcludes="yes" 
		destdir="javaDoc" 
		author="true" 
		version="true" 
		use="true" 
		classpathref="annotations.classpath" 
		splitindex="true" 
		nonavbar="true"
		windowtitle="F1 Betting Game : Documentation">
			<doctitle>
				<![CDATA[<h1>F1 Betting Game</h1>]]>
			</doctitle>
		<bottom>
			<![CDATA[Copyright © Philipp Boss.<br/> <b>Please contact Philipp Boss in case of questions</b>]]>
		</bottom>
	</javadoc>
</target>

This task creates the javadoc for the package com.pbo.* inside the src-folder and stores the created doc files inside the javaDoc folder.

The parameter nonavbar hides the navigation bar in the created doc files. For my opinion this generates more „clean“ javadoc pages. The windowtitle is the title of the html-page (what you can see in your browser tab), the doctitle is the one beeing displayed inside the web page. The value of bottom is beeing displayed at the end of the page.

Here you can see the created page:

Javadoc created Webpage

Javadoc created Webpage

Sync Thunderbird Addressbook with Baikal using carddav

 IT  Kommentare deaktiviert für Sync Thunderbird Addressbook with Baikal using carddav
Jul 032014
 

In my last article I described how to import Contacts from your Goggle Account. Now I will describe how to bring those (and also every other) contacts to baikal and how to setup synchronisation between Thunderbird and Baikal.

First of all we need to install the Sogo-Adapter Addon for Thunderbird (this provides DAV)

Sogo-Adapter

Sogo-Adapter

After that, we are able to create a Remote-Address Book in Thunderbird. Here you can see my settings for that address book.

The value „philipp“ is the ID of my Baikal-user, „default“ is the token-id of my address book in baikal (see related Baikal article).

Remote Address book

Remote Address book

Now you can move your contacts from your Google Addressbook to your Baikal Address book via drag&drop (or via copy&paste). After you have moved/copied the contacts to the baikal address book you should run the sync-command to push the contacts to your baikal-server (right-click on your baikal address book and hit „Synchronize“).

After that, the contacts should be available in your baikal database. Let’s to a simple check:

philipp@eliteX:~$ mysql -u baikalUser -p
Enter password: 
// removed some simple lines...

mysql> use baikal
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A

Database changed
mysql> select count(*) from cards;
+----------+
| count(*) |
+----------+
|      323 |
+----------+
1 row in set (0.00 sec)

 

In my case, all of my 323 Google Contacts were stored in the database. Now I can sync every device and tool (Thunderbird, Android, etc.) with my baikal address book.

Related articles:

Import Google Contacts to Thunderbird AddressBook

 IT  Kommentare deaktiviert für Import Google Contacts to Thunderbird AddressBook
Jul 032014
 

For my project to move all my contacts to Baikal (see related articles) it is necessary to bring my google contacts to Thunderbirds Addressbook.

Install Gcontactsync addon for thunderbird:

gContactsSync Plugin

gContactsSync Plugin

Create a new Address Book which should be used to import the Google Contacts. Also configure your google-Accont. If you are using app-passowords, you have to generate one in your google account.

I have set the Sync-Type to Read-Only, because I just want to receive the contacts, but not to modify them (also it is more secure if we do some mistakes).

gcontactSync Addressbook

gcontactSync Addressbook

Now you can close the window and click on „gcontactSync“ -> „Sync“ to receive the contacts. They should now be available in your GoogleContacts Addressbook.

Related articles:

Baikal: Setup a user and addressbook

 IT  Kommentare deaktiviert für Baikal: Setup a user and addressbook
Jul 032014
 

Open the web-admin-page of baikal: http://yourhost/<path_to_baikal>/admin/

In the admin-menu you can create a new user, in my case I created the user „Philipp“:

Create User

Create User

Now create a addressbook for that user:

Create Addressbook

Create Addressbook

Addressbook token id

Addressbook token id

 

That’s all. For synchronisation you need the card-dav URL:

// general
http://localhost/baikal/card.php/addressbooks/<user>/<addressbook_token_id>/

// in this case
http://localhost/baikal/card.php/addressbooks/philipp/default/

Related articles: