mina-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernd Fondermann <bf_...@brainlounge.de>
Subject Re: Move Vysper from sandbox
Date Mon, 22 Jun 2009 21:33:28 GMT
Julien Vermillard wrote:
> Le Sun, 21 Jun 2009 11:22:34 +0200,
> Bernd Fondermann <bf_jak@brainlounge.de> a écrit :
> 
>> Emmanuel Lecharny wrote:
>>> Niklas Gustavsson wrote:
>>>> Hi
>>>>
>>>> For Vysper, the export page has been updated
>>>> (https://issues.apache.org/jira/browse/VYSPER-47), Bernd has
>>>> assembled a list of all contributors
>>>> (https://issues.apache.org/jira/browse/VYSPER-45) and I think we've
>>>> done the due diligence even though the issue is not closed
>>>> (https://issues.apache.org/jira/browse/VYSPER-44). Therefore, I
>>>> think it's time to move Vysper out of the sandbox. If no one
>>>> objects, I'll start a vote in a few days.
>>>>   
>>> Well, sorry for being a bit a PITA, but I would like to see more
>>> javadoc in the project. We already have been burnt (and still
>>> are !!!) with MINA suffering from such a problem that I would like
>>> to avoid it again.
>>>
>>> I don't mean it should be perfect, but at least, a first pass is
>>> necessary.
>> Of course we need more javadoc, just as we need more code comments,
>> unit tests, user doc etc. All of that gets my +1.
>>
>> To turn this into an actually task, could you point out areas/classes
>> that especially lack javadoc?
>>
>>> I know this sounds painful, but this is also the price to pay to be
>>> able to jump into the code, to get more committers involved, and to
>>> receive less basic questions on the mailing list.
>> At this point, I'd be happy to actually receive *more* questions ;-)
>>
>> For me, writing javadoc isn't painful at all, when I see something
>> under-documented. I generally consider documentation a quality issue,
>> not a quantity issue.
>>
>>   Bernd
> 
> Hi,
> The followed rule for MINA Javadoc is :
>  - a comment in each class header
>  - doco on each public/protected method (or on the parent class public
>    method with inherited tags)
> 
> The main point is to help user to understand the public API,
> for the internal doco it's more flexible and it's good to hear great
> feedback from Michael :)

Let's step back a little bit for a second for some general observations.

MINA is a 'framework', a 'toolset'. Other people use it as a basic
foundation to build their own stuff on it. They don't install it in the
classical way, they don't configure it like a server would typically be
configured. Instead, they download it and dive in. They have to know how
everything/most of it works. There is no other documentation than what's
on mina.apache.org. They have to rely on the javadoc to figure things
out. (BTW, there are not many exhausting MINA examples, that's something
that concerns me more than the javadoc.)

Vysper is a 'server'. It's a standalone application which gets
installed, configured and monitored in a very classical way.
It's an implementation of a well-defined standard (RFCs and XEPs).
People download it, but I don't expect that Vysper's users will get a
very deep understanding of it. Developers can (should/must) consult the
XMPP specs which explains everything very precise. That's why Vysper has
@SpecCompliant annotations and MINA hasn't. If you look at Vysper code
and haven't read RFCs 3920 + 3921, you probably will run into troubles
understanding it.

Conclusion: MINA and Vysper are very different.

So, back on topic.

I don't think every single setter/getter method in Vysper needs javadoc.
Frankly, I've got better things to do with my time than add redundancies.
Often, I sit before a class and think about what I should write into the
header javadoc. But nothing good comes to my mind other than repeating
what is already in the class name. I keep going on with something else.

In Vysper's commit log history you will notice one or more doc'athons
where a lot of doc is added. I will keep doing that. It's fun.

> 
> Anyway the javadoc issue could be blocking for a 1.0 release, but
> looks like we aren't there :)

No, were aren't there by far. A 0.1 is more what I have in mind, but
this will still take some time, too.

> 
> On the sandbox moving I think it's a great idea, since the community
> around Vysper is growing.

I'm +/-0 on this, I trust you guys to decide this.

   Bernd

Mime
View raw message