![[de]](/mwf/flags/de.png "Germany")
Let's upload the reference documentation to openclonk.org. We inherited the Clonk Rage documentation, which requires a python, xsltproc and gettext to build. (And hhc.exe for the chms, and some other, more easily replaced stuff.) This is probably not available on openclonk.org, is it?Another question is whether we want to retain the web annotation stuff. That never really took off on clonk.de, but some useful comments are there.
I'd also like to match the doc theme to the forum/wiki/bugtracker themes. Are those easily available somewhere?
![[es]](/mwf/flags/es.png "Spain")
So we stick to the old XML documentation style for clonk developers? Actually I would like to slowly slowly go to a wiki-style-documentation since it's much easier for collaboration.I or Clonkonaut will check about that. We might have Python, but of course we can't install our own programs (hhc.exe?)@Python,...
What do you mean exactly with "are those easily available somewhere"?
hhc.exe is the html help work thing that builds the chm. Some windows user will have to do those builds.And there's not much to collaborate about with the documentation - somebody has to describe what a part of the engine does, and that's it. We probably shouldn't put tutorials in there, though.
Another idea might be to use ikiwiki to enable online editing of the documentation.
OK, perhaps we are not talking about the same thing. Let me define some stuff:- There is the source code documentation which document the interfaces and give a rough overview which operates with what (like Javadoc).
- For C4Script - there are the reference pages which document the engine functions
- Then there is the developer documentation which includes general description of clonk scripting, defcore, categories and whatnot
- At last, what I have been missing up till now is documentation of the object systems such as alchemy, magic, gear of knights and the functions and interfaces associated. The Hazard doc (attachment) is a prime example of what I mean here.
As I mentioned, I think the documentation of the engine source can be covered by comments in the source code, a short guide of what does what - as you say. Additionally, we could perhaps make use of something like auto-generated JavaDoc.
The present Clonk developer documentation are mainly reference pages with some additional texts about the editor, directory structure etc. However, to include more detailed and better updated descriptions in the documentation, I propose to put this stuff into the Wiki (Example: http://www.wesnoth.org/wiki/Create). The question of the "Somebody" who documents widens to all people who want contribute - even if it's just a sentence or correcting a word instead of only the people who have write access to the repository or people who would create a patch. I think I don't need to explain more, everybody knows the Wiki-principle, it's just easier and more suggesting to contribute. The wiki, then, could be a good place for tutorials, integrated into the whole thing, too.
Of course we don't want to produce unnecessary work, so having the XML reference pages parallel to an additional documentation suggests itself.
Attachment: Hazard.chm (786k)
> However, to include more detailed and better updated descriptions in the documentation, I propose to put this stuff into the Wiki
Well, I won't do that work, but do not let that hinder you. But please don't loose features like automatic generation of function lists for editors.
Both Doxygen and NaturalDocs support JavaDoc syntax. So we don't actually need to settle on one app to start documenting the classes and it's methods already. The basic syntax:
/**
* A description of the method
*
* @param id the ID of the object to create
* @param foo another description
* @return the return value...
*/
(Non required tags are amongst others @see, @author and @throws ... see google)
Powered by mwForum 2.29.7 © 1999-2015 Markus Wichitill
