Where is MyBatis API Doc?

[Hesey Wang]

I extract mybatis-3.0.4-javadoc and open it, but I found it nearly
have nothing.

Where can I find the API Doc for MyBatis?

[Clinton Begin]

http://code.google.com/p/mybatis/downloads/detail?name=MyBatis-3-User-Guide.pdf

[Eduardo Macarron]

There are some documented classes, not many. There was a time when the javadoc was available in the site but I do not why but now it is not there. Maybe a problem with the space or the time it got to deploy the site.

2012/10/29 Jerry O <gober...@gmail.com>

No, sorry.  The user guide is very useful and informative, and I'll compliment the author(s).  But it is not JavaDoc.  In case you are unfamiliar with JavaDoc (and, I regret to say, most Java developers nothing whatsoever about it), here are a couple of examples from some other more or less unrelated projects.

 

http://docs.oracle.com/javase/7/docs/api/index.html
http://static.springsource.org/spring/docs/3.1.x/javadoc-api/

 

Has such documentation been written for MyBatis, and, if so, is it available on the web site?

On Sunday, March 13, 2011 11:17:00 AM UTC-4, Clinton Begin wrote:

http://code.google.com/p/mybatis/downloads/detail?name=MyBatis-3-User-Guide.pdf

On Sat, Mar 12, 2011 at 11:14 PM, Hesey Wang <hes...@gmail.com> wrote:

...Where can I find the API Doc for MyBatis?

[Jerry O]

I can understand why they might have taken the "so called" JavaDoc off the site - it reveals the lack of documentation in the code.  I found another post to the effect that one can obtain the JavaDoc from the mybatis-3.x-bundle.zip.  I downloaded mybatis-3.0.6-bundle.zip (because that is the version my current employer/project are using) and extracted the JavaDoc jar.  To my dismay, I discovered that all that had been done was to run javadoc against the comment-free code base, and bundle the resulting (essentially worthless) html into a .jar.  (And why a .jar not a .zip, I don't know.)

 

What this confirms is that the developers of this project apparently don't know anything about JavaDoc, and that they possibly haven't looked at the JavaDoc for other projects (the JDK, Spring, Log4J, etc. etc. ad nauseum), so they're unaware that JavaDoc is more than a list of classes, methods and packages, and consists of html comments embedded in the code between /** */  I find this quite surprising for a project of this duration and complexity, and one which is otherwise well documented.  Even with a wealth of supporting user manuals, sample code, articles, how-tos and whatnot, JavaDoc is still, IMHO, essential.  When I work(ed) extensively with Spring, I found myself often referring to the reference material and the JavaDoc, for often, I wanted to know what variations were available, and what they did, etc.

 

Moreover, writing class and method level documentation, at least in a skeletal way, before writing more than skeletal code, disciplines one's mind to focus on separation of concerns, definitions, specifications and so forth.  In my mind, this is evidence that the class, method, etc. are well designed.  As these things are lacking here, and I am new to the tool, this gives me some reservations.

 

But, as I said, there are countless Java developers who don't even know that JavaDoc is supposed to be html, never mind what it's supposed to contain.  I'm just surprised that this is the case here.

 

Perhaps if I eventually decide that this is somehow or another well designed after all, I might try to help adding JavaDoc, my family permitting.  But it should have been done in the first place.

[Eduardo Macarron]

Hi Jerry. You can be sure that there is very clever people in the team and they know javadoc very well :) 

It is just that nobody wrote it, nothing more.

The package build was changed in 3.1 version. Javadocs are now bundled. From an API perspective there is not a big difference between the 3.1.1 and the 3.0.6. 

For older versions, I am afraid you should checkout the project and execute mvn javadoc:javadoc, the javadoc will appear in target/site/apidocs

2012/10/29 Jerry O <gober...@gmail.com>

[Larry Meadors]

As the guy who wrote nearly all the javadocs for ibatis 1, I
respectfully think you're talking out of inexperience. :-)

Javadocs for mybatis would be pretty useless unless you're doing
development on mybatis because you really don't use that much of the
API. Here's an example of using mybatis (from a project I'm working
on):

public class ArtistService {
private final ArtistMapper artistMapper;
@Autowired
public ArtistService(ArtistMapper artistMapper) {
this.artistMapper = artistMapper;
}
// code to use the artistMapper (which is my interface...)
}

See the mybatis reference in there? Me either, because it's not there.

Instead of talking trash, what exactly are you looking for?

Larry

[Clinton Begin]

Jerry, 

I'm the one who wrote the majority of the MyBatis core and the user guide. I'm the one who did not write the docs. I can assure you that after 15 years of Java development, I know perfectly well what JavaDocs are. I chose not to write them. 

    * Why? Because this is a volunteer effort and I didn't have time and I prioritized it low.

    * Why? Because I don't often use Javadocs outside of the JDK (which are great), and thus I simply didn't want to. I prefer user guides, books, blogs, etc. 

I personally prefer this experience:

    http://www.stripesframework.org/display/stripes/Quick+Start+Guide

Over this experience:

    http://stripes.sourceforge.net/docs/current/javadoc/

You may choose to not use the framework because of this difference in perceived value of JavaDocs. You may also choose to offer your services to add JavaDocs to the project, as Larry did 10 years ago for iBATIS 1.

But you may not be disrespectful of the team or members on this list by way of your arrogant assumptions.  That will ensure that you are no longer welcome to participate on it.

Regards,

Clinton

[Bogdan Tanase]

The MyBatis user guide it's pretty awesome! I've picked up mybatis basics within a day due to that guide; I didn't even notice the (lack of) javadocs ...

On the other hand, most of the important stuff happen in xml mapper files, so I don't see how javadocs would be useful there.

[Steve Hill]

To throw in my 2 cents.

I concur with the others, the documentation provided is great; it has
examples of almost everything and the few times it hasn't answered a
particular question an internet search on posting on this list has found
the answer and within short order too. The i/mybatis team has done a
fantastic job which has brought me back to using it on projects time and
time again. I am always amazed by the power of the open source community
and what they have accomplished.

In the event you really need to understand the internals, I recommend
hooking up a debugger and stepping through the code (yes we have done this
occasionally to understand how the plugins work) If someone feels
JavaDoc's would be a useful addition I am sure no one of the team would
begrudge them writing it and added to the project.

Thanks!
Steve.

>>> material *and *the JavaDoc, for often, I wanted to know what variations

>>> were available, and what they did, etc.
>>>
>>> Moreover, writing class and method level documentation, at least in a

>>> skeletal way, *before *writing more than skeletal code, disciplines

>>> one's mind to focus on separation of concerns, definitions,
>>> specifications
>>> and so forth. In my mind, this is evidence that the class, method,
>>> etc.

>>> *are* well designed. As these things are lacking here, and I am new to

>>> the tool, this gives me some reservations.
>>>
>>> But, as I said, there are countless Java developers who don't even know
>>> that JavaDoc is supposed to be html, never mind what it's supposed to
>>> contain. I'm just surprised that this is the case here.
>>>
>>> Perhaps if I eventually decide that this is somehow or another well
>>> designed after all, I might try to help adding JavaDoc, my family
>>> permitting. But it should have been done in the first place.
>>>
>>> On Monday, October 29, 2012 1:52:32 PM UTC-4, Eduardo wrote:
>>>
>>>> There are some documented classes, not many. There was a time when the
>>>> javadoc was available in the site but I do not why but now it is not
>>>> there.
>>>> Maybe a problem with the space or the time it got to deploy the site.
>>>>
>>>> 2012/10/29 Jerry O <gober...@gmail.com>
>>>>
>>>> No, sorry. The user guide is very useful and informative, and I'll

>>>>> compliment the author(s). But it is *not *JavaDoc. In case you are

>>>>> unfamiliar with JavaDoc (and, I regret to say, most Java developers

>>>>> *nothing
>>>>> whatsoever *about it), here are a couple of examples from some other

>>>>> more or less unrelated projects.
>>>>>

>>>>> http://docs.oracle.com/javase/**7/docs/api/index.html<http://docs.oracle.com/javase/7/docs/api/index.html>
>>>>> http://static.springsource.**org/spring/docs/3.1.x/javadoc-**api/<http://static.springsource.org/spring/docs/3.1.x/javadoc-api/>

>>>>>
>>>>> Has such documentation been written for MyBatis, and, if so, is it
>>>>> available on the web site?
>>>>>
>>>>> On Sunday, March 13, 2011 11:17:00 AM UTC-4, Clinton Begin wrote:
>>>>>

>>>>>> http://code.google.com/p/**mybat**is/downloads/detail?name=**MyBat**
>>>>>> is-3-User-Guide.pdf<http://code.google.com/p/mybatis/downloads/detail?name=MyBatis-3-User-Guide.pdf>

[Clinton Begin]

PS:  My response is in no way an "excuse" for not having JavaDocs, nor is it a lack of respect for JavaDocs on my part.  I think projects like Stripes have done a great job with theirs.  Simone and Larry have proposed writing JavaDocs in the past.  It really just does come down to time and priority.

Thanks to the community for your support.

Cheers,

Clinton

[Dridi Boukelmoune]

Hi,

I agree with the idea that a javadoc site give a poor user experience,
but it's very useful in your IDE when you mess up with the internals.
Eclipse for instance has a nice JavaDoc view I usually show while I'm
coding (also useful for a real-time rendering when writing my own
docs) and you get a big tooltip during auto-completion.

I'm just saying, not trolling :)

Dridi

--
Dridi Boukelmoune
Développeur/Formateur

GSM : +33 (0)6 17 91 14 23

[Clinton Begin]

I agree 100% Dridi.  

Clinton