Fill out JavaDoc comments for Tutti

[hwray]

We need to add some documentation to our codebase. If we do it in official JavaDoc style, we can automatically extract it into an actual HTML JavaDoc, linked together wiki-style.

Here's the official JavaDoc guidelines:

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

And a direct example of its use in the Java codebase itself (Collections class):

http://www.docjar.net/html/api/java/util/Collections.java.html

[JayThomason]

I did the documentation for MainActivity here https://github.com/JayThomason/Tutti/commit/93471856cbb602f5efa9e429d93eea82b3836423

It's pretty straightforward to generate the javadoc. Just start your comments with "/**", like this:

    /**
     * Stops logging a jam, resets the welcome text, and stops all discovery
     * related tasks.
     * 
     * @see android.app.Activity#onRestart()
     */

and it should be a valid javadoc.

To generate the docs in Eclipse you have to go to Project > Generate Javadoc.

From here you need to choose a place to generate the javadoc and the path to the javadoc executable, which is in your jdk folder (you'll need to figure out where you installed java by searching your computer). Since we are supposed to document every method choose the []private option (generate documentation for all methods & fields, private and public).

Please don't commit the actual generated javadocs /doc folder (if you put it in the Tutti directory). We can just make a website using Github pages when we're done that holds the javadoc html files.

[JayThomason]

Also it is potentially a pain trying to correctly generate all of the javadoc (for all classes in our project) and having everything link up correctly (at least it was for me in Windows) so when writing javadocs you don't necessarily need to generate the docs to test it.

[JayThomason]

As of https://github.com/JayThomason/Tutti/commit/6d7ea56f1c3a091fe01fdcb3241295b2cdc90ad2 I have mostly documented 7 of the 27 classes in our source. I expect that we don't need to document NanoHTTPD.java or the DragSort code so that leaves 15 classes to comment with javadocs.

[hwray]

I've added documentation for Client, Globals, HelpMenuActivity, and DatabaseHandler (300 lines in DBHandler even with super basic comments! wow such documentation)

[hwray]

MusicLibraryLoaderThread, RequestLibraryThread, SettingsMenuActivity, and Song are also documented now.

[hwray]

Just added documentation for JoinJamActivity and the Server. Looks like all we have left is:

• DiscoveryManager
• Jam
• Logger
• LoggerAlarmReceiver

[hwray]

Documentation is finished for Jam, our last big major class. The remaining classes I'll mostly leave to @JayThomason , as he implemented them and has a better understanding of how they work:

• DiscoveryManager
• Logger
• LoggerAlarmReceiver

[JayThomason]

Cool. I'll get that done today.

[JayThomason]

Done: https://github.com/JayThomason/Tutti/commit/7daa595fccf0591f54f95cd3047ced846354e053