Marko Lindqvist writes: > No comments? I kind of expected at least Jacob as our main > documentation guru to have an opinion. Just in case I changed subject > of this email to one that might catch his attention better :-)
Hey, I mainly concern myself with user documentation. Developer documentation is another kettle of worms entirely. ;) > Now that we are putting doxygen generated documentation online one way > or other we should also consider improving it. > > Doxygen (like other similar tools) requires specially crafted comments > in source code (its markup) to build better documentation from. Should > we add such markup to freeciv code? It's also important to decide if > we want to use some other markup (and some other tool) instead, before > we have invested a lot of working time to add doxygen markup. Well, I've worked in a few codebases where Doxygen has been used, although not on this scale, and I've never introduced it myself. It seems pretty popular, particularly for C codebases, so I guess it'll remain well-supported, and I'm not aware of a "better" choice (but I haven't gone looking, and I've not worked with anything else similar). In my (limited!) experience it's rather good for basic documentation that's closely tied to code structures, so long as you don't try to do anything too fancy with it (in terms of formatting, or swathes of text that aren't tied to any particular code construct -- I think our wiki would be better for that sort of thing). I wouldn't be unhappy committing to Doxygen markup. (<http://en.wikipedia.org/wiki/Comparison_of_documentation_generators> seems like a reasonable place to shop for alternatives, if anyone feels like it. By the features and support, nothing else stands out as obviously much better than Doxygen.) > If we don't decide against doxygen markup (if we at least allow people > to add it, if not require it), I'd like to see some official policy > added to CodingStyle. It should govern markup usage on new code and > code being touched. Doxygen allows several ways of doing the markup (dunno if you can disable some of them in the configuration), so we'd probably want to set some standards for that. > I don't expect us to systematically go through all the existing code > to add markup now. We may decide to add some specific subset of > documentation systematically when doing so would make documentation > significantly better with small investment. Function headers are already in a pretty standard format. We could consider auto-converting those to Doxygen markup to get basic per-function documentation; the current Doxygen output is pretty indigestible without. Autogenerated code is another place where we could get a quick win (and compensate somewhat for the fact that important files like packets.def will probably be otherwise invisible in Doxygen output). To start with, we could try applying such automatic conversions locally between checkout and running Doxygen in some sort of regular build, if we don't want to commit to Doxygen and create noise in svn. However, I think we'd get the most benefit from checking an autoconversion into svn, and then we can improve it by adding \param, \returns, hyperlink etc markup on an ad-hoc basis. It'll be a bit of a pain for porting between branches, but we've survived such "noisy" changes before (e.g., assert->fc_assert, my*()->fc_*()). By the way, I guess that the current freeciv.doxygen relies on you having done a full build first, so that autogenerated code is in place? Perhaps it should be added as a Makefile target so that it gets all the dependencies it needs. _______________________________________________ Freeciv-dev mailing list [email protected] https://mail.gna.org/listinfo/freeciv-dev
