Re: [Help-glpk] Doxygen

[Robbie Morrison]

Hello Andrew, Xypron, all

I take it that applying 'doxygen' retrospectively to a
project like GLPK would require a major effort.  Is that
what is being proposed by xypron?

I am also guessing that 'doxygen' has developed since
we last had this discussion in 2004:

  http://lists.gnu.org/archive/html/help-glpk/2004-09/msg00026.html

>From the other side, I guess that 'doxygen'
documentation would reduce the "entry cost" to
someone wishing to modify the code and perhaps
even contribute back to the mainline development.

best wishes, Robbie

------------------------------------------------------------
To:           glpk xypron <address@hidden>
Subject:      Re: [Help-glpk] Doxygen
Message-ID:  <address@hidden>
From:         Andrew Makhorin <address@hidden>
Date:         Sat, 16 Jun 2012 13:00:53 +0400
------------------------------------------------------------

> Hi Xypron,
>
> Sorry for a long delay in my response.
>
>> currently a cross reference to the GLPK code is
>> missing.
>>
>> Doxygen gives the possibility to generate a
>> documentation from the existing code.
>>
>> For an example see
>> http://www.xypron.de/projects/winglpk/doxygen/html/glpk_8h.html#afb1c0fb8674d9d9680ec9c42f922176b
>>
>> In the appendix you will fill configuration file
>> "Doxyfile" and filter "doxyfilter" (which should be
>> chmod 755).
>>
>> The filter discovers all lines containg "* NAME" and
>> indicates to doxygen that this is the start of a
>> special comment block, cf.
>> http://www.stack.nl/~dimitri/doxygen/docblocks.html
>>
>> I suggest to add the two files to the root directory
>> of the GLPK source distribution.
>>
>> To create the documentation in directory
>> glpk-4.47/doc/doxygen navigate to directory glpk-4.47
>> and invoke command doxygen.
>>
>> Prerequisites for usage are:
>> - Doxygen
>> - sed
>> - Graphviz
>>
>> More complete documentation could be produced after adjusting the
>> comment style in glpk a bit, e.g.
>> int var; /*!< Detailed description after the member */
>> instead of
>> int var; /* Detailed description after the member */
>
> Thank you for you suggestion.
>
> I have a negative experience on working with packages
> documented in such way and wouldn't like to use it.
>
> Could you provide an example of that that should be
> cross referenced? Do you mean routine names, terms, or
> what? I think that it would quite easy to make
> necessary additions in the LaTeX files. If you mean the
> source code, there exist some packages to automatically
> format it and produce, say, html or pdf pages provided
> with the index of all program objects and
> hyperlinks. However, I don't find that such way
> facilitates studying the source code.
>
> Andrew Makhorin

---
Robbie Morrison
PhD student -- policy-oriented energy system simulation
Technical University of Berlin (TU-Berlin), Germany
University email (redirected) : address@hidden
Webmail (preferred)           : address@hidden
[from Webmail client]