Add methods and class descriptions throughout the JavaDoc

eldur / jwbf

Java Wiki Bot Framework is a library to maintain Wikis like Wikipedia based on MediaWiki.

http://jwbf.sourceforge.net/

Apache License 2.0

78 stars 33 forks source link

Add methods and class descriptions throughout the JavaDoc #22

Open fhocutt opened 10 years ago

fhocutt commented 10 years ago

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

eldur commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

Any doc improvement would be appreciated :-)

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

fhocutt commented 10 years ago

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 commented 10 years ago

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 commented 10 years ago

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