Doxygen

[xypron]

Hello Andrew,

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 */

Best regards

Xypron

--
Empfehlen Sie GMX DSL Ihren Freunden und Bekannten und wir
belohnen Sie mit bis zu 50,- Euro! https://freundschaftswerbung.gmx.de



_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[Andrew Makhorin]

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




_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[xypron]

Hello Andrew,

I did not mean to replace or change the pdf documentation.

When trying to read your coding to understand it better it is helpful,
to have the coding in a form where you can easily navigate between the
different modules.

Adding a configuration file for Doxygen would allow the interested
person to easily generate such a cross referenced coding. Adding the
configuration file would not necessitate to make any other changes in GLPK.

Best regards

Xypron

On 16.06.2012 11:00, Andrew Makhorin wrote:

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

_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[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 <xypron.glpk@...>
Subject:      Re: [Help-glpk] Doxygen
Message-ID:  <1339837253.1890.58.camel@corvax>
From:         Andrew Makhorin <mao@...>
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) : morrison@...
Webmail (preferred)           : robbie@...
[from Webmail client]



_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[xypron]

Hello Robbie,
>
> 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 did not request to change any existing GLPK code.
I did not suggest to replace the existing documentation.

I just suggested to add a doxygen configuration file which allows the person interested to easily apply doxygen to generate a cross referenced code listing and documentation.

An example of the output produced is
http://www.xypron.de/projects/winglpk/doxygen/html/glpk_8h.html#afb1c0fb8674d9d9680ec9c42f922176b

With the links provided you can easily find out
- in which C file a function is coded
- the call hierarchy

You can easily navigate between the functions.

I set up the configuration file in a way that it makes use of the existing comments of Andrew's coding.

Best regards

Xypron
--
NEU: FreePhone 3-fach-Flat mit kostenlosem Smartphone!                                  
Jetzt informieren: http://mobile.1und1.de/?ac=OM.PW.PW003K20328T7073a

_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[Andrew Makhorin]

> > 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 did not request to change any existing GLPK code.
> I did not suggest to replace the existing documentation.
>
> I just suggested to add a doxygen configuration file which allows the
> person interested to easily apply doxygen to generate a cross
> referenced code listing and documentation.
>
> An example of the output produced is
> http://www.xypron.de/projects/winglpk/doxygen/html/glpk_8h.html#afb1c0fb8674d9d9680ec9c42f922176b
>
> With the links provided you can easily find out
> - in which C file a function is coded
> - the call hierarchy
>
> You can easily navigate between the functions.
>
> I set up the configuration file in a way that it makes use of the
> existing comments of Andrew's coding.
>

I was confused by "cross reference" - these diagrams are usually called
"call graphs".

Okay, please post me the doxygen configuration file and please teach me
how I should include it in the distribution. (It seems to me that there
exists a standard posix utility that does the same job.)


Andrew Makhorin



_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[Robbie Morrison]

Hi all

------------------------------------------------------------
To:           glpk xypron <xypron.glpk@...>
Subject:      Re: [Help-glpk] Doxygen
Message-ID:  <1340117967.2100.9.camel@corvax>
From:         Andrew Makhorin <mao@...>
Date:         Tue, 19 Jun 2012 18:59:27 +0400
------------------------------------------------------------

[snip]

>> With the links provided you can easily find out
>>
>> - in which C file a function is coded
>> - the call hierarchy
>>
>> You can easily navigate between the functions.

[snip]

> I was confused by "cross reference" - these diagrams
> are usually called "call graphs".
>
> Okay, please post me the doxygen configuration file and
> please teach me how I should include it in the
> distribution. (It seems to me that there exists a
> standard posix utility that does the same job.)
>
> Andrew Makhorin

Hi Andrew, Xypron, others

Just some background really.  Wikipedia has a page
on call-graphs and, in particular, a list of static
call-graph generators:

  http://en.wikipedia.org/wiki/Call_graph

With some more searching, it seems that POSIX only
specifies an output format and that 'cflow' can
generate POSIX-compliant output:

  http://www.gnu.org/software/cflow/manual/html_node/Output-Formats.html

I guess Xypron will put up the doxygen-generated
HTML output on a website somewhere?  Maybe on:

  http://www.gnu.org/software/glpk/

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



_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk

[xypron]

Dear Andrew,

please, find appended an archive with the Doxygen configuration file. It
should be placed in the root directory of the distribution, e.g. as
glpk-4.48/Doxyfile

To create the documentation the packages doxygen and graphviz are needed.

Just go to the directory with Doxyfile and execute doxygen.

The doxygen documentation will be created in glpk-4.48/doc/doxygen.

Please, adjust the following line according to the release number:
PROJECT_NUMBER         = 4.47

>> I was confused by "cross reference"
You can navigate from to the code and will find links inside the code,
e.g. in line 489 of
http://www.xypron.de/projects/winglpk/doxygen/html/glpapi12_8c_source.html#l00489
you can navigate to the documentation of xerror and from there to the
declaration in glpenv.h, from there to the documentation of glp_error_, ....
 
Best regards

Xypron

On 19.06.2012 16:59, Andrew Makhorin wrote:

> I was confused by "cross reference" - these diagrams are usually called
> "call graphs".
>
> Okay, please post me the doxygen configuration file and please teach me
> how I should include it in the distribution. (It seems to me that there
> exists a standard posix utility that does the same job.)
>
>
> Andrew Makhorin
>
>
>

_______________________________________________
Help-glpk mailing list
Help-glpk@...
https://lists.gnu.org/mailman/listinfo/help-glpk