Add methods and class descriptions throughout the JavaDoc

[fhocutt]

The JavaDoc is very sparse and has few descriptions. The library would be easier to use with more method and class descriptions.

[eldur]

Sorry this seems to be true, but the task description is a little too general. Where are you missing javadoc comments?

I don't want to write comments like this

/**
* writes the article
* @param article the article
*/
public void writeArticle(Article article) {

[fhocutt]

Understood! I think there is room to make some of the existing comments clearer, so I will be working on that in the next week or so.

Another question: how would you describe the overall structure of the framework? As I understand it:

• To work on a wiki, you create a MediaWikiBot for it. This can access various methods for (for instance) getting articles, logging in, making and posting edits, getting site metadata, etc.
• Most of the underlying work is done by the methods in /core, under the surface. You could use these if you wanted more direct access to the API than you could get with the methods in /mediawiki.
• The higher-level methods that you can use to act on the wiki are in /mediawiki/actions.

Is that basically correct?

[eldur]

Any doc improvement would be appreciated :-)

To your second question: your package structure description is correct.

[fhocutt]

As I'm looking at this, I'm seeing that having some higher-level documentation available would help new users pick up on the structure of the framework and know where to start with writing their own bots, and I'm interested in writing some. Knowing how to describe the framework structure is a good starting point, thank you!

Once I write this, where would you like to post it? I think that adding it to the README would make the README too long and complicated. It might be possible to put it in the JavaDoc index page, or to add some documentation to the sf homepage. What do you think?

[eldur]

What do you think about a developerDocs.md file with a reference from README.md? Because markdown is easier to write and looks better than javadoc or plain HTML at sf.net

[fhocutt]

Sure, sounds good. I'll start on that after I'm done working on the README.