| Summary: | ASTERISK-20259: [patch] Update Doxygen Configuration for make progdocs | ||||
| Reporter: | Andrew Latham (lathama) | Labels: | patch | ||
| Date Opened: | 2012-08-19 14:40:12 | Date Closed: | 2021-12-13 07:55:22.000-0600 | ||
| Priority: | Major | Regression? | No | ||
| Status: | Closed/Complete | Components: | Documentation | ||
| Versions: | SVN 13.18.4 | Frequency of Occurrence | |||
| Related Issues: |
| ||||
| 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 1062 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 update 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 Notes: 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. http://lists.digium.com/pipermail/asterisk-dev/2012-October/057084.html By: Andrew Latham (lathama) 2012-10-11 09:49:03.981-0500 All 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 {noformat} trunk$ svn diff | grep "\-" | grep -v "\-\-\-" | wc -l 678 trunk$ svn diff | grep "+" | grep -v "+++" | wc -l 449 trunk$ {noformat} 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: {noformat} 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 ) </application> ^ 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 {noformat} 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. [https://gerrit.asterisk.org/c/asterisk/+/17578|https://gerrit.asterisk.org/c/asterisk/+/17578] By: Friendly Automation (friendly-automation) 2021-12-13 07:57:11.752-0600 Change 17577 merged by George Joseph: progdocs: Update Makefile. [https://gerrit.asterisk.org/c/asterisk/+/17577|https://gerrit.asterisk.org/c/asterisk/+/17577] By: Friendly Automation (friendly-automation) 2021-12-13 08:05:20.203-0600 Change 17582 merged by George Joseph: progdocs: Update Makefile. [https://gerrit.asterisk.org/c/asterisk/+/17582|https://gerrit.asterisk.org/c/asterisk/+/17582] By: Friendly Automation (friendly-automation) 2021-12-13 08:05:23.830-0600 Change 17576 merged by George Joseph: progdocs: Update Makefile. [https://gerrit.asterisk.org/c/asterisk/+/17576|https://gerrit.asterisk.org/c/asterisk/+/17576] | ||||