Summary:ASTERISK-20259: [patch] Update Doxygen Configuration for make progdocs
Reporter:Andrew Latham (lathama)Labels:patch
Date Opened:2012-08-19 14:40:12Date Closed:2021-12-13 07:55:22.000-0600
Versions:SVN 13.18.4 Frequency of
is the original version of this clone:ASTERISK-20412 Update Doxygen Configuration for make progdocs
Environment:Attachments:( 0) ast_make_doxygen_happier_big.diff
( 1) doxygen_check.diff
( 2) doxygen_partial_update.diff
( 3) doxygen_partial.diff
( 4) make_progdocs.diff
( 5) readme.diff
( 6) sysnux.patch
Description:Attempting to add documentation and work on doxygen errors I found that the configuration file was out of date.  After a doxygen -u asterisk-ng-doxygen there were fewer warnings and errors reported.
Comments:By: Andrew Latham (lathama) 2012-08-19 15:37:00.225-0500

Doxygen does not like the xhtml empty tags (eg..  <allalone/>), they are not suggested in html5 either so lets use the good old fall back.

By: Andrew Latham (lathama) 2012-08-19 15:37:50.603-0500

Some doxygen escape issues.

Missing params and such.  Please take a look and help out by checking my work here.

By: Andrew Latham (lathama) 2012-08-19 17:16:05.256-0500

Ok, going a little crazy here... half way done...

svn diff | grep "^+" | wc -l

By: Andrew Latham (lathama) 2012-08-19 18:59:39.008-0500

complete diff, getting large...

By: Andrew Latham (lathama) 2012-08-19 22:42:46.313-0500

Testing by compiling, running "make progdocs" and have only 5% of the warnings...

By: Andrew Latham (lathama) 2012-08-20 17:43:19.109-0500

Attached diff "ast_make_doxygen_happier_big.diff" is working out well today.  The patch edits or adds 1237 lines in 69 files.  What is the best way to handle large patches like this?  This work only affects comments and the Doxygen config.

By: Andrew Latham (lathama) 2012-08-21 08:18:47.034-0500

I noticed http://www.asterisk.org/doxygen/trunk/index.html is running Doxygen 1.5.6

Debian Stable (Squeeze) is using Doxygen 1.7.1-2 and there are new versions abound.  I will add a diff with doxygen -u in the Makefile

By: Matt Jordan (mjordan) 2012-08-22 09:31:34.069-0500

I thought about putting this up on Review Board, but I'm not sure there'd be a lot of useful comments generated from that.  We probably can just go ahead and commit this and fix any obvious flaws from the resulting doxygen.

By: Andrew Latham (lathama) 2012-08-22 09:35:28.226-0500

Agreed.  This will always be a work in progress and my patch is just a huge first step.

By: Andrew Latham (lathama) 2012-08-23 09:56:52.188-0500


I am looking at https://wiki.asterisk.org/wiki/display/~pabelanger/sample+config and testing now.  Working with app_skel items.

I found the doxygen configuration too restrictive.  Reviewed and testing with defaults produces much more usable output.  "addons/ooh323c/src" contains it's own Doxygen mainpage and documentation.  Excluding "addons/ooh323c/src" for now.

By: Andrew Latham (lathama) 2012-08-27 09:23:55.513-0500

Partial diff of typos and things I would really like committed...

By: Andrew Latham (lathama) 2012-08-28 20:23:18.974-0500

Sorry, I clicked the re-triage button by accident...

By: Andrew Latham (lathama) 2012-08-30 09:39:56.502-0500

Matt, an updated diff with more simple fixes.

By: Andrew Latham (lathama) 2012-09-17 14:51:53.550-0500

A simple update for the README file to note the location of the wiki.

By: Andrew Latham (lathama) 2012-09-22 16:08:02.431-0500

I would like to ask: What machine is currently running the online Doxygen daily?  Can this machine have a more recent version of Doxygen?

By: Andrew Latham (lathama) 2012-10-01 17:13:30.605-0500


1. "./configure" does not stop "make progdocs" if doxygen is missing
2. Full docs are ~328mb without "dot" files, much larger with, testing requires a SSD, there is no other way...
3. Some of the pages and documentation are so out of date it is shocking.  Step back and look closely.
4. svn blame / svn praise need I say more....
5. enabling logging on doxygen fixed the most problems.
6. Search bar is hidden if treeview is enabled. hmm

By: Andrew Latham (lathama) 2012-10-02 08:00:28.585-0500

Trying the list again.


By: Andrew Latham (lathama) 2012-10-11 09:49:03.981-0500


While working on Doxygen I have found many inline credits in the
"\file" stanza and other locations of apps, resources, core components
and etc.  I started the work of merging all this info into the CREDITS
file.  I then cleaned up the formatting of CREDITS white-space and
even noticed some duplication.  This is an ongoing issue and one topic
that I discussed with Tilghman was about the formatting of an email
address for anti spam.  In response to our emails I realized that many
of the email addresses are out of date...  eg tilghman@digium.com
bounces mail. A persons name and email in combination are an
identifier currently.

Everyone please offer your opinions on the following points.

1. Should email addresses be altered for anti spam purposes?

2. Could we maybe update the repotools "authors" file with the license
numbers for each person?

3. Should we link to or transclude the repotools "authors" file?

4. Should all inline credits be moved to CREDITS or should I just
create a Doxygen group for them?

5. Thanks for making this far, have you checked your name/email
correctness in Asterisk/Credits or the repotools "authors" file?

By: Andrew Latham (lathama) 2012-10-11 17:47:09.763-0500

Looking better all the time http://www.asterisk.org/doxygen/trunk/index.html

Search works, configuration files grouping looking good

need to attack the ./configure check for Doxygen.  I tested on a new VM and it did not have Doxygen, so make progdocs failed.

By: Andrew Latham (lathama) 2012-10-12 12:51:58.348-0500

have ./configure and the Makefile check for Doxygen working now, yeah!  testing testing testing

By: Andrew Latham (lathama) 2012-10-12 15:26:01.578-0500

updates for Makefile and Autoconf to check if Doxygen is installed.

ran bootstrap.sh and tested many times.

By: Andrew Latham (lathama) 2012-10-13 10:55:50.056-0500

Doxygen Output Directories

In the past the output directory has been set to "doc/api/html/"  During testing I wanted to test the man-page creation and some other output.  I changed the base directory to "doc" and then the html output directory to "api".

This is a change and I should have checked before I committed.  Matt Jordan caught the change while looking at the online documentation and I quickly and incorrectly committed it to be "api/api/".  I have now corrected this.

If anyone wishes to get alternative output from Doxygen they can install the needed libraries for latex, PDF, XMLDOC or other and run Doxygen.  All output should go to the based directory of "doc" and possibly a sub-directory depending on the configuration defaults.

By: Andrew Latham (lathama) 2012-10-13 13:41:06.109-0500

Battling issue with multiple README files

So Doxygen uses the last match that it can find and because the README that we want is in the base directory and there are various other README files then I can not get the right one used.  From a overall point of view we should not have so many README files.

By: Jean-Denis Girard (jdg) 2012-10-13 14:44:05.627-0500

Change my contact in the CREDITS file

By: Andrew Latham (lathama) 2012-10-14 16:38:46.162-0500

This will be fun
trunk$ svn diff | grep "\-" | grep -v "\-\-\-" | wc -l
trunk$ svn diff | grep "+" | grep -v "+++" | wc -l

By: Andrew Latham (lathama) 2012-10-18 09:00:37.763-0500

In progress, updates have been made to trunk.  I need to understand how far back these changes should be backported.

By: Richard Mudgett (rmudgett) 2012-10-18 15:15:26.639-0500

Got documentation validation error during compile:
make[1]: Entering directory `/home/rmudgett/projects/sa/asterisk/trunk'
CC="cc" CXX="" LD="" AR="" RANLIB="" CFLAGS="" LDFLAGS="" make -C menuselect CONFIGURE_SILENT="--silent" makeopts
make[2]: Entering directory `/home/rmudgett/projects/sa/asterisk/trunk/menuselect'
make[2]: `makeopts' is up to date.
make[2]: Leaving directory `/home/rmudgett/projects/sa/asterisk/trunk/menuselect'
/usr/bin/xmlstarlet val -d doc/appdocsxml.dtd doc/core-en_US.xml
doc/core-en_US.xml:947: element application: validity error : Element application content does not follow the DTD, expecting (synopsis? , syntax? , description? , see-also?), got (synopsis syntax description para variablelist see-also )
doc/core-en_US.xml:917: element application: validity error : Element application content does not follow the DTD, expecting (synopsis? , syntax? , description? , see-also?), got (synopsis syntax description para variablelist see-also )
doc/core-en_US.xml - invalid
make[1]: *** [validate-docs] Error 1
make[1]: Leaving directory `/home/rmudgett/projects/sa/asterisk/trunk'
make: *** [_cleantest_all] Error 2

By: Andrew Latham (lathama) 2012-10-18 15:19:14.232-0500

Richard, that is for XMLdocs and not Doxygen.  I will be happy to help you fix this but its a different part of the documentation mess.

By: Andrew Latham (lathama) 2012-10-18 15:21:11.811-0500

Richard, that is part of "AlarmReceiver"....

By: Andrew Latham (lathama) 2012-11-02 12:46:42.938-0500

FYI, wiki urls with url encoded chars and Doxygen don't get along too well

By: Andrew Latham (lathama) 2013-01-01 12:53:16.913-0600

Working on https://wiki.asterisk.org/wiki/display/AST/LDAP+Realtime+Driver and res_config_ldap.c right now.  Module load includes and attempt to connect even if not configured which is another issue.

By: Andrew Latham (lathama) 2013-01-21 11:50:09.739-0600

Consider enabling INTERNAL_DOCS as some developers feel that it is normal to use for every tag.

By: Friendly Automation (friendly-automation) 2021-12-13 07:55:24.260-0600

Change 17578 merged by Friendly Automation:
progdocs: Update Makefile.


By: Friendly Automation (friendly-automation) 2021-12-13 07:57:11.752-0600

Change 17577 merged by George Joseph:
progdocs: Update Makefile.


By: Friendly Automation (friendly-automation) 2021-12-13 08:05:20.203-0600

Change 17582 merged by George Joseph:
progdocs: Update Makefile.


By: Friendly Automation (friendly-automation) 2021-12-13 08:05:23.830-0600

Change 17576 merged by George Joseph:
progdocs: Update Makefile.