[deepamehta-devel] Javadoc

[Urs Lerch]

Hi,

as I'm sitting there most of the day writing on my PhD I'm sorry to say
that I have neither the motivation nor the energy to work on another
documentation.

Anyhow, in my experience it is better to complement a guide at the time
when there's a real need. In other words, if I have a problem and can't
find the answer in the developer guide, I should ask and then add the
information I recieved in my own words.

Regards,
Urs


Am Freitag, den 14.03.2008, 01:42 +0100 schrieb Jörg Richter:
> Dear Developers,
> 
> thank you for your considerations about making DeepaMehta more 
> attractive for external developers!
> 
> Please note: we already have javadoc-generated API documentation at the 
> DeepaMehta website. Including call-references for important methods, a 
> tweaked stylesheet to match the website design, handcrafted package 
> comments and backlink to the DeepaMehta website. See "Documentation -> 
> Developer Documentation -> API Documentation".
> www.deepamehta.de/docs/apidocs/
> 
> A lot of further documentation is found in the DeepaMehta source code 
> itself. (Some people told me they have rarely seen a source code with 
> such in-depth code documentation.) Of course there is -- as always -- 
> room for improvement.
> 
> In my opinion the tool discussion is secondary and doesn't help here 
> very much. For the time being the Javadoc tool does the job good 
> enough. In the end the essential benefit is produced not by the tool 
> but by the programmer who has the discipline and dedication to write 
> well-thought code documentation (an art in itself). There helps nothing 
> but practicing it.
> 
> An automatized nighty build of the API Docs AND Binaries is reasobale 
> in principle but for the time being would not help too much people. 
> Urs, i will not hesitate to create a shell account at the DeepaMehta 
> server for you to be able to establish the nightly build process. But 
> actually I would appreciate if you would focus on another 
> high-priority-task in the same domain.
> 
> => In order to make DeepaMehta more attractive for external developers 
> the most important task is to write a comprehensive DeepaMehta 
> framework documentation. That is a documentation that deals at the 
> conceptual level, above the API-level. The beginning of such a 
> "Development Guide" is already available at the DeepaMehta website 
> (Documentation -> Developer Documentation -> Development Guide) but 
> apparently it is incomplete and would benefit from examples.
> www.deepamehta.de/docs/devguide.html
> 
> Urs, I would appreciate very much if you're interested in 
> extending/rewriting the DeepaMehta Development Guide resp. if you could 
> motivate someone else to do so. Writing the DeepaMehta Development 
> Guide could be an attractive challenge for technical writers who want 
> to contribute to an innovative and ambitous open source project :-)
> 
> Regards,
> Jörg
> 
> www.deepamehta.de
> 
> 
> On 13.03.2008, at 20:50, Urs Lerch wrote:
> 
> > Hi,
> >
> > Yes, I agree that double the information wasn't a good idea. So doxygen
> > is fine with me.
> >
> > And I really think that a nightly build is a MUST! But how do we get
> > there? Who could manage that? Is there anybody else out there?
> >
> > I don't know what the infrastructure looks like, but I guess there
> > should be a little bit of machine resource left for this little task. 
> > If
> > I had the account information I would do it, though I'm not really an
> > expert in such things - in my former job I used to have my "ants" :)
> >
> > Regards,
> > Urs
> >
> >
> > Am Donnerstag, den 13.03.2008, 16:54 +0100 schrieb Enrico Schnepel:
> >> Hi,
> >>
> >>> (1) javadoc compatible (no compromise there!)
> >> and it knows some more javadoc tags as javadoc itself does
> >> you could document groups of functions for example.
> >>
> >>> (2) integrated in eclipse
> >> http://eclox.eu/
> >> I am prefering the command line way...
> >> what about an automated checkout and a doxygen build on a nighly 
> >> basis.
> >> the build log could be also send to the dev-list if the where errors 
> >> in the
> >> build. - continious integration! and... if we have some unit tests 
> >> these may
> >> run too.
> >>
> >>> (3) easy to set up
> >> using a wizard - it is
> >>
> >>> So, why don't we use both of them, javadoc and doxygen? It's not that
> >>> much work, at least with javadoc. And if we see, after some time, 
> >>> that
> >>> there is only one documentation used, we could easily skip the other
> >>> then.
> >> this would double the information and it would make no sense to me if 
> >> i would
> >> see two documentation links on the website.
> >>
> >>> In my opinion it is important that there's a documentation in the 
> >>> code
> >>> at all, and that it is done in a widely used and accepted
> >>> standard/style. Anything that helps as a motivation to do this is
> >>> welcome.
> >> +1
> >>
> >> Enrico
> >> _______________________________________________
> >> deepamehta-devel mailing list
> >> deepamehta-devel at lists.berlios.de
> >> https://lists.berlios.de/mailman/listinfo/deepamehta-devel
> >
> > _______________________________________________
> > deepamehta-devel mailing list
> > deepamehta-devel at lists.berlios.de
> > https://lists.berlios.de/mailman/listinfo/deepamehta-devel
> >
> 
> _______________________________________________
> deepamehta-devel mailing list
> deepamehta-devel at lists.berlios.de
> https://lists.berlios.de/mailman/listinfo/deepamehta-devel