Re: Using Doxygen with Angband

Peter Blake wrote:
On Jan 25, 2:22 pm, Andrew Sidwell <takka...@xxxxxxxxx> wrote:
Peter Blake wrote:
....
Doxygen has its own annoying syntax, which I dislike. (I'm told JavaDoc
and other similar systems use it too, but I don't code Java or C#.) I
mean the gunk like @brief, @param etc. Comments are for humans to read,
not computers; it's better to have a syntax which is both human-readable
and machine-readable without having to put all these special at-tags
everywhere. Hence, I would prefer c), but have never found anything
that fits my requirements. (I'm happy to argue out my case on this one,
but I think it might the issue of aesthetics comes into it somewhere.)

The argument for using the "gunk" (IMO) gets stronger the more
important it is that the documentation stand separate from the code.
That argument doesn't apply here though.

Perhaps. I'm not a professional coder, so I wouldn't know. :)

As Pete has implied, the current Angband documentation generally a long
winding mass of (outdated) comments and todos, with nothing much in the
way of API documentation. I rewrite comments as I go, but it would be
good to set aside some time just to do a file-by-file rewrite, I suppose.

If we can agree on some parameters (e.g. for style and length of
comments), I'd be interested in helping out with this.

Well, that being the case...

I've been documenting things in the header files at the moment, just because that's where I tend to look up function definitions. I think that really we want them in the source files instead, though. The only problem I can think of with that approach is when source files have multiple functions with the same name but different ifdefs -- e.g. the new directory-scanning code (in z-file.c), which uses entirely different implementations on POSIX and Windows.

For an example of the kind of style I've been using, see:
http://dev.rephial.org/trac/browser/trunk/src/z-file.h
http://dev.rephial.org/trac/browser/trunk/src/z-msg.h

If you want to come up with a list of things that would make comments fit your ideas of how they should be, we could go from there. I just tend to write in the style that comes out naturally. :)

[Note also that the development version of Angband is quite a different beast when it comes to file organisation to 3.0.9 -- lots of things have been split out into new files, chiefly with the aim of making the code easier to maintain and learn.]

At some point, the function declarations should probably be autogenerated from the .c files, as it's implied they are now, for consistency's sake.

--
Andrew Sidwell
http://rephial.org/
.

Relevant Pages

  • Re: moving "tools" into the tools/ directory?
    ... I did some moving of such files from Documentation to tool in a git ... As a followup the original rename git tree ... Move Documentation/connector source files to tools/connector ...
    (Linux-Kernel)
  • Re: Component help generator
    ... > 1) I want to put all my documentation in my source files. ... > like to make a hyperlink directly in my source code documentation. ... "See Also or Keyword comments are added to the source file with semi-colons between keywords. ...
    (borland.public.delphi.thirdpartytools.general)
  • FraserSoft changing ISPs
    ... problems getting to the web site. ... Source files are imported and used ... then these can be used to create the full documentation ... Alternatively, GenHelp ...
    (borland.public.delphi.thirdpartytools.general)
  • Re: javadoc like system for C wanted
    ... documentation inside of Java source files. ... * gobble - gobble some characters from a string ... To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx ...
    (Debian-User)
  • Re: The language of the KRS
    ... >>> in the days since the interview on 26 december. ... >> a marriage between Svantepolk Knutson and a descendant to Birger ... >> the ribbons fits the box. ... That is to say the documentation ...
    (sci.archaeology)
Loading