Where is MyBatis API Doc? - mybatis-user

The old Google Groups will be going away soon, but your browser is incompatible with the new version.
Message from discussion Where is MyBatis API Doc?
Received-SPF: pass (google.com: domain of bftan...@gmail.com designates 74.125.83.42 as permitted sender) client-ip=74.125.83.42;
MIME-Version: 1.0
In-Reply-To: <CAKt2ckJ9po=rRqSv_CQaOraapt4GiEihNhi_R5fuWsY0Jym...@mail.gmail.com>
References: <f3531075-7f14-4323-b75a-28492fc3c...@v11g2000prb.googlegroups.com>
 <AANLkTikpPY3GBeZD=A21G2PKOjU74tN+dbANT+X2-...@mail.gmail.com>
 <07d0cfde-10d2-4a7a-9245-028e5e020353@googlegroups.com> <CAAdrJxy4V4GJkowHZ-saVYR3_fYBURxfkHAwGSwdZeRS04T...@mail.gmail.com>
 <01a6174e-20f6-4e1e-996b-a3d90d6d6676@googlegroups.com> <CAKt2ckJ9po=rRqSv_CQaOraapt4GiEihNhi_R5fuWsY0Jym...@mail.gmail.com>
From: Bogdan Tanase <bftan...@gmail.com>
Date: Mon, 29 Oct 2012 22:55:57 +0200
Message-ID: <CADHo+3NOyC8ZhGSy_3GiKW+EVTcnz9upEhmH6RKrvBnCQZM...@mail.gmail.com>
Subject: Re: Where is MyBatis API Doc?
To: mybatis-user@googlegroups.com
Content-Type: multipart/alternative; boundary=047d7b6244b89d2df104cd38e60c

--047d7b6244b89d2df104cd38e60c
Content-Type: text/plain; charset=ISO-8859-1

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 <clinton.be...@gmail.com>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 <goberle...@gmail.com> 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 <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>
>>>>>
>>>>> On Sat, Mar 12, 2011 at 11:14 PM, Hesey Wang <hes...@gmail.com> wrote:
>>>>>
>>>>>> ...Where can I find the API Doc for MyBatis?
>>>>>
>>>>>
>>>>>
>>>
>

--047d7b6244b89d2df104cd38e60c
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

The MyBatis user guide it&#39;s pretty awesome! I&#39;ve picked up mybatis =
basics within a day due to that guide; I didn&#39;t even notice the (lack o=
f) javadocs ...<div><br></div><div>On the other hand, most of the important=
 stuff happen in xml mapper files, so I don&#39;t see how javadocs would be=
 useful there.<br>

<br><div class=3D"gmail_quote">On Mon, Oct 29, 2012 at 8:58 PM, Clinton Beg=
in <span dir=3D"ltr">&lt;<a href=3D"mailto:clinton.be...@gmail.com" target=
=3D"_blank">clinton.be...@gmail.com</a>&gt;</span> wrote:<br><blockquote cl=
ass=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;p=
adding-left:1ex">

Jerry,=A0<div><br></div><div>I&#39;m the one who wrote the majority of the =
MyBatis core and the user guide.=A0I&#39;m the one who did not write the do=
cs.=A0I can assure you that after 15 years of Java development, I know perf=
ectly well what JavaDocs are.=A0I chose not to write them.=A0<div>



<br></div><div>=A0 =A0 * Why? Because this is a volunteer effort and=A0I di=
dn&#39;t have time and I prioritized it low.</div><div><br></div><div>=A0 =
=A0 * Why? Because I don&#39;t often use Javadocs outside of the JDK (which=
 are great), and thus I simply didn&#39;t want to. I prefer user guides, bo=
oks, blogs, etc.=A0</div>



<div><br></div><div>I personally prefer this experience:</div><div><br></di=
v><div>=A0 =A0=A0<a href=3D"http://www.stripesframework.org/display/stripes=
/Quick+Start+Guide" target=3D"_blank">http://www.stripesframework.org/displ=
ay/stripes/Quick+Start+Guide</a></div>



<div><div><br></div><div>Over this experience:</div><div><br></div><div>=A0=
 =A0=A0<a href=3D"http://stripes.sourceforge.net/docs/current/javadoc/" tar=
get=3D"_blank">http://stripes.sourceforge.net/docs/current/javadoc/</a></di=
v></div>

<div><br></div>

<div>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.<div>



<br></div><div>But you may not be disrespectful of the team or members on t=
his list by way of your arrogant assumptions. =A0That will ensure that you =
are no longer welcome to participate on it.</div><div><br></div><div>Regard=
s,</div>



<div>Clinton</div><div><div class=3D"h5"><div><br><div class=3D"gmail_quote=
">On Mon, Oct 29, 2012 at 12:23 PM, Jerry O <span dir=3D"ltr">&lt;<a href=
=3D"mailto:goberle...@gmail.com" target=3D"_blank">goberle...@gmail.com</a>=
&gt;</span> wrote:<br>

<blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1p=
x #ccc solid;padding-left:1ex">

<div>I can understand why they might have taken the &quot;so called&quot; J=
avaDoc off the site - it reveals the lack of documentation in the code.=A0 =
I found another post to the effect that one can obtain the JavaDoc from the=
 mybatis-3.x-bundle.zip.=A0 I downloaded mybatis-3.0.6-bundle.zip (because =
that is the version my current employer/project are using) and extracted th=
e JavaDoc jar.=A0 To my dismay, I discovered that all that had been done wa=
s to run javadoc against the comment-free code base, and bundle the resulti=
ng (essentially worthless) html into a .jar.=A0 (And why a .jar not a .zip,=
 I don&#39;t know.)</div>




<div>=A0</div>
<div>What this confirms is that the developers of this project apparently d=
on&#39;t know anything about JavaDoc, and that they possibly haven&#39;t lo=
oked at the JavaDoc for other projects (the JDK, Spring, Log4J, etc. etc. a=
d nauseum), so they&#39;re unaware that JavaDoc is more than a list of clas=
ses, methods and packages, and consists of html comments embedded in the co=
de between /** */=A0 I find this quite surprising for a project of this dur=
ation and complexity, and one which is otherwise well documented.=A0 Even w=
ith a wealth of supporting user manuals, sample code, articles, how-tos and=
 whatnot, JavaDoc is still, IMHO, essential.=A0 When I work(ed) extensively=
=A0with Spring, I found myself often referring to the reference material <e=
m>and </em>the JavaDoc, for often, I wanted to know what variations were av=
ailable, and what they did, etc.</div>




<div>=A0</div>
<div>Moreover, writing class and method level documentation, at least in a =
skeletal way, <em>before </em>writing more than skeletal code, disciplines =
one&#39;s mind to focus on separation of concerns, definitions, specificati=
ons and so forth.=A0 In my mind, this is=A0evidence that the class, method,=
 etc. <em>are</em> well designed.=A0 As these things are lacking here, and =
I am new to the tool, this gives me some reservations.</div>




<div>=A0</div>
<div>But, as I said, there are countless Java developers who don&#39;t even=
 know that JavaDoc is supposed to be html, never mind what it&#39;s suppose=
d to contain.=A0 I&#39;m just surprised that this is the case here.</div>




<div>=A0</div>
<div>Perhaps if I eventually decide that this is somehow or another well de=
signed after all, I might try to help adding JavaDoc, my family permitting.=
=A0 But it should have been done in the first place.</div><div>


<div><br>On Monday, October 29, 2012 1:52:32 PM UTC-4, Eduardo wrote:</div>
</div><blockquote style=3D"BORDER-LEFT:#ccc 1px solid;MARGIN:0px 0px 0px 0.=
8ex;PADDING-LEFT:1ex" class=3D"gmail_quote"><div>There are some documented =
classes, not many. There was a time when the javadoc was available in the s=
ite but I do not why but now it is not there. Maybe a problem with the spac=
e or the time it got to deploy the site.<br>



<br>
</div><div class=3D"gmail_quote">2012/10/29 Jerry O <span dir=3D"ltr">&lt;<=
a>gober...@gmail.com</a>&gt;</span><div><br>
<blockquote style=3D"BORDER-LEFT:#ccc 1px solid;MARGIN:0px 0px 0px 0.8ex;PA=
DDING-LEFT:1ex" class=3D"gmail_quote">
<div>No, sorry.=A0 The user guide is very useful and informative, and I&#39=
;ll compliment the author(s).=A0 But it is <em>not </em>JavaDoc.=A0 In case=
 you are unfamiliar with JavaDoc (and, I regret to say, most Java developer=
s <em>nothing whatsoever </em>about it), here are a couple of examples from=
 some other more or less unrelated projects. </div>




<div>=A0</div>
<div><a href=3D"http://docs.oracle.com/javase/7/docs/api/index.html" target=
=3D"_blank">http://docs.oracle.com/javase/<u></u>7/docs/api/index.html</a><=
br><a href=3D"http://static.springsource.org/spring/docs/3.1.x/javadoc-api/=
" target=3D"_blank">http://static.springsource.<u></u>org/spring/docs/3.1.x=
/javadoc-<u></u>api/</a></div>




<div>=A0</div>
<div>Has such documentation been written for MyBatis, and, if so, is it ava=
ilable on the web site?</div>
<div><br>On Sunday, March 13, 2011 11:17:00 AM UTC-4, Clinton Begin wrote:<=
/div>
<blockquote style=3D"BORDER-LEFT:#ccc 1px solid;MARGIN:0px 0px 0px 0.8ex;PA=
DDING-LEFT:1ex" class=3D"gmail_quote"><a href=3D"http://code.google.com/p/m=
ybatis/downloads/detail?name=3DMyBatis-3-User-Guide.pdf" target=3D"_blank">=
http://code.google.com/p/<u></u>mybat<u></u>is/downloads/detail?name=3D<u><=
/u>MyBat<u></u>is-3-User-Guide.pdf</a><br>



<br>
<div class=3D"gmail_quote">On Sat, Mar 12, 2011 at 11:14 PM, Hesey Wang <sp=
an dir=3D"ltr">&lt;<a>hes...@gmail.com</a>&gt;</span> wrote:<br>
<blockquote style=3D"BORDER-LEFT:#ccc 1px solid;MARGIN:0px 0px 0px 0.8ex;PA=
DDING-LEFT:1ex" class=3D"gmail_quote">...Where can I find the API Doc for M=
yBatis?</blockquote></div><br></blockquote></blockquote></div></div><br></b=
lockquote>



</blockquote></div><br></div></div></div></div></div>
</blockquote></div><br></div>

--047d7b6244b89d2df104cd38e60c--
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
