Julien Vermillard wrote: > Le Sun, 21 Jun 2009 11:22:34 +0200, > Bernd Fondermann <[email protected]> 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
