Re: [Freeciv-Dev] Doxygen documentation markup

[Marko Lindqvist]

On 19 February 2011 00:26, Jacob Nevins  wrote:
> 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. ;)

 Maybe, but you still gave excellent answer.

 I have to ask if you consider modder support your area. Those people
*use* freeciv to *develop* custom content, such as rulesets and
scenarios.

 This comes up as I have been discussing about freeciv in civ2
scenario creation group Scenario League's forums.
Some of those people have tried to get started with freeciv modding,
but our documentation has not been good enough to get them started.
I've written some very drafty document drafts for them, but problem in
general probably remains. Whole discussion at
http://forums.civfanatics.com/showthread.php?t=412202


 - ML

___
Freeciv-dev mailing list
Freeciv-dev@gna.org
https://mail.gna.org/listinfo/freeciv-dev

Re: [Freeciv-Dev] Doxygen documentation markup

[Jacob Nevins]

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.

(
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

[Freeciv-Dev] Doxygen documentation markup

[Marko Lindqvist]

On 10 February 2011 23:59, Marko Lindqvist  wrote:
> 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.
> 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. 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.

 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 :-)


 - ML

___
Freeciv-dev mailing list
Freeciv-dev@gna.org
https://mail.gna.org/listinfo/freeciv-dev