[deepamehta-devel] Javadoc
Jörg Richter
jri at deepamehta.de
Fr Mär 14 01:42:40 CET 2008
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
>
Mehr Informationen über die Mailingliste devel