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
Freeciv-dev@gna.org
https://mail.gna.org/listinfo/freeciv-dev

Reply via email to