[deepamehta-devel] Javadoc

[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
>