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: softfail (google.com: domain of transitioning dridi.boukelmo...@zenika.com does not designate 207.126.144.117 as permitted sender) client-ip=207.126.144.117;
MIME-Version: 1.0
In-Reply-To: <CAKt2ckLMSqpo=ytYAtrJ8s4xUMP4wyRsELON1nFKdcE25RV...@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>
 <CAKt2ckLMSqpo=ytYAtrJ8s4xUMP4wyRsELON1nFKdcE25RV...@mail.gmail.com>
From: Dridi Boukelmoune <dridi.boukelmo...@zenika.com>
Date: Tue, 30 Oct 2012 19:06:16 +0100
Message-ID: <CABtDKm5L7R1ZReaOB21HLyvN46xbp6bz5xe43+ZuVoFktGT...@mail.gmail.com>
Subject: Re: Where is MyBatis API Doc?
To: mybatis-user@googlegroups.com
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

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 <clinton.be...@gmail.com> wr=
ote:
> 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 writin=
g
> 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 <clinton.be...@gmail.com>
> wrote:
>>
>> Jerry,
>>
>> I'm the one who wrote the majority of the MyBatis core and the user guid=
e.
>> I'm the one who did not write the docs. I can assure you that after 15 y=
ears
>> of Java development, I know perfectly well what JavaDocs are. I chose no=
t 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, book=
s,
>> 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 long=
er
>> 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 wa=
s to
>>> run javadoc against the comment-free code base, and bundle the resultin=
g
>>> (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 looke=
d 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 classe=
s,
>>> methods and packages, and consists of html comments embedded in the cod=
e
>>> between /** */  I find this quite surprising for a project of this dura=
tion
>>> 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) extensivel=
y
>>> with Spring, I found myself often referring to the reference material a=
nd
>>> 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 w=
ell
>>> 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 t=
here.
>>>> 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 n=
othing
>>>>> whatsoever about it), here are a couple of examples from some other m=
ore 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=3DMyBatis-3-U=
ser-Guide.pdf
>>>>>>
>>>>>> On Sat, Mar 12, 2011 at 11:14 PM, Hesey Wang <hes...@gmail.com> wrot=
e:
>>>>>>>
>>>>>>> ...Where can I find the API Doc for MyBatis?
>>>>>>
>>>>>>
>>>>
>>
>



--=20
Dridi Boukelmoune
D=E9veloppeur/Formateur

GSM : +33 (0)6 17 91 14 23
Create a group - Google Groups - Google Home - Terms of Service - Privacy Policy
Account Options
