Where is MyBatis API Doc?

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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?
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

Clinton Begin
Administrator
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 <[hidden email]> wrote:
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?

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

Jerry O
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.
 
 
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 <<A href="javascript:" target=_blank gdf-obfuscated-mailto="DTTDfZBexQ4J">hes...@...> wrote:
...Where can I find the API Doc for MyBatis?

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

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 <[hidden email]>
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.
 
 
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 <[hidden email]> wrote:
...Where can I find the API Doc for MyBatis?


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

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.

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 <<A href="javascript:" target=_blank gdf-obfuscated-mailto="zsmDcJoBoMUJ">gober...@...>
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.
 
 
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 <[hidden email]> wrote:
...Where can I find the API Doc for MyBatis?


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

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 <[hidden email]>
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.

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 <[hidden email]>

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.
 
 
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 <[hidden email]> wrote:
...Where can I find the API Doc for MyBatis?



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

Larry Meadors
In reply to this post by Jerry O
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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

Clinton Begin
Administrator
In reply to this post by Jerry O
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:


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

On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <[hidden email]> wrote:
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.

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 <[hidden email]>

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.
 
 
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 <[hidden email]> wrote:
...Where can I find the API Doc for MyBatis?



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

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.

On Mon, Oct 29, 2012 at 8:58 PM, Clinton Begin <[hidden email]> wrote:
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:


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

On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <[hidden email]> wrote:
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.

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 <[hidden email]>

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.
 
 
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 <[hidden email]> wrote:
...Where can I find the API Doc for MyBatis?




Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

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.

> 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.
>
> On Mon, Oct 29, 2012 at 8:58 PM, Clinton Begin
> <[hidden email]>wrote:
>
>> 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
>>
>> On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <[hidden email]> wrote:
>>
>>> 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.
>>>
>>> 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 <[hidden email]>
>>>>
>>>>  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>
>>>>>>
>>>>>> On Sat, Mar 12, 2011 at 11:14 PM, Hesey Wang <[hidden email]>
>>>>>> wrote:
>>>>>>
>>>>>>> ...Where can I find the API Doc for MyBatis?
>>>>>>
>>>>>>
>>>>>>
>>>>
>>
>


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

Clinton Begin
Administrator
In reply to this post by 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

On Mon, Oct 29, 2012 at 12:58 PM, Clinton Begin <[hidden email]> wrote:
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:


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

On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <[hidden email]> wrote:
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.

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 <[hidden email]>

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.
 
 
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 <[hidden email]> wrote:
...Where can I find the API Doc for MyBatis?




Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

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

On Tue, Oct 30, 2012 at 3:45 PM, Clinton Begin <[hidden email]> wrote:

> 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
>
>
> On Mon, Oct 29, 2012 at 12:58 PM, Clinton Begin <[hidden email]>
> wrote:
>>
>> 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
>>
>> On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <[hidden email]> wrote:
>>>
>>> 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.
>>>
>>> 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 <[hidden email]>
>>>>
>>>>> 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 <[hidden email]> wrote:
>>>>>>>
>>>>>>> ...Where can I find the API Doc for MyBatis?
>>>>>>
>>>>>>
>>>>
>>
>



--
Dridi Boukelmoune
Développeur/Formateur

GSM : +33 (0)6 17 91 14 23
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Where is MyBatis API Doc?

Clinton Begin
Administrator
I agree 100% Dridi.  

Clinton


On Tue, Oct 30, 2012 at 12:06 PM, Dridi Boukelmoune <[hidden email]> wrote:
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

On Tue, Oct 30, 2012 at 3:45 PM, Clinton Begin <[hidden email]> wrote:
> 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
>
>
> On Mon, Oct 29, 2012 at 12:58 PM, Clinton Begin <[hidden email]>
> wrote:
>>
>> 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
>>
>> On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <[hidden email]> wrote:
>>>
>>> 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.
>>>
>>> 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 <[hidden email]>
>>>>
>>>>> 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 <[hidden email]> wrote:
>>>>>>>
>>>>>>> ...Where can I find the API Doc for MyBatis?
>>>>>>
>>>>>>
>>>>
>>
>



--
Dridi Boukelmoune
Développeur/Formateur

GSM : <a href="tel:%2B33%20%280%296%2017%2091%2014%2023" value="+33617911423">+33 (0)6 17 91 14 23

Loading...