# [bug #56004] Cannot build doxygen documentation due to unresolved references

10 messages
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 URL:                    Summary: Cannot build doxygen documentation due to unresolved references                  Project: lwIP - A Lightweight TCP/IP stack             Submitted by: freddie_chopin             Submitted on: Tue 26 Mar 2019 11:25:32 AM UTC                 Category: Documentation                 Severity: 3 - Normal               Item Group: Compiler Warning                   Status: None                  Privacy: Public              Assigned to: None              Open/Closed: Open          Discussion Lock: Any          Planned Release: None             lwIP version: git head     _______________________________________________________ Details: doxygen version 1.8.15 Trying to build lwipdocs target results in multiple errors like the one below: -- >8 -- >8 -- >8 -- >8 -- >8 -- >8 -- >8 -- ... /home/freddie/Elektronika/PC/Projects/lwip-ppp-test/lwip/doc/doxygen/main_page.h:244: error: unable to resolve reference to compiler_abstraction.\n' for \ref command (warning treated as error, aborting now) ... Exiting... ninja: build stopped: subcommand failed. -- >8 -- >8 -- >8 -- >8 -- >8 -- >8 -- >8 -- It seems that these are caused by following code:  * @ref compiler_abstraction.\n while it works like this:  * @ref compiler_abstraction .\n Fixing the first one results in another one being found, then another one and another and so on...     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #1, bug #56004 (project lwip): Care to provide a patch?     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #2, bug #56004 (project lwip): > Care to provide a patch? Sure, I can fix that, but first I wanted a confirmation that adding whitespace where necessary is the "right way" to fix this. Maybe there's some other issue at my side or sth like that. Just let me know and I can send a patch (;     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #3, bug #56004 (project lwip): I think the fix is ok. (the problem doesn't happen with my local doxygen version and the one on the Travis CI server)     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #4, bug #56004 (project lwip): > the problem doesn't happen with my local doxygen version and the one on the Travis CI server Could you tell me what version is it? Maybe you could try locally with a more recent doxygen version (1.8.15). The problem here is that even doxygen's manual uses section names with dots: http://www.doxygen.nl/manual/commands.html#cmdpageSo this may be a doxygen bug, problem in Doxyfile or I don't-know-what-else - not necessarily a problem in lwip's documentation. I have to investigate a little more (;     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #5, bug #56004 (project lwip): Local system is 1.8.14, Travis: 1.8.6     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #6, bug #56004 (project lwip): I attach two patches which fix the documentation build for doxygen 1.8.15 with as little visual change as possible. (file #46645, file #46646)     _______________________________________________________ Additional Item Attachment: File name: 0001-Fix-doxygen-ref-in-altcp.c.patch Size:1 KB     File name: 0002-Fix-and-simplify-newlines-in-doxygen-documentation.patch Size:27 KB         _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #7, bug #56004 (project lwip): I can reproduce it using latest doxygen. However, this looks like a bug in doxygen to me. It's specified that \n can be used for
: http://www.doxygen.nl/manual/commands.html#cmdn - so I at least want to avoid applying your second patch. The latest version was released after more than 2 years with so many changes that I didn't even read the changelog to find out whether it's a feature. The changes you needed to make are huge :-(     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel
Open this post in threaded view
|

## [bug #56004] Cannot build doxygen documentation due to unresolved references

 Follow-up Comment #8, bug #56004 (project lwip): > The latest version was released after more than 2 years with so many changes that I didn't even read the changelog to find out whether it's a feature. True, doxygen's development is not the fastest of them all, which means that without the fix/workaround, the problem will appear for significant amount of time and for significant amount of people. Even if you report a bug, you have no guarantees that it will get fixed in reasonable time (I speak from experience, as - if I remember correctly - a few years ago I reported 2 or 3 doxygen bugs and they are still unsolved, with zero replies from the author). > The changes you needed to make are huge :-( But in fact these changes are extremely simple, so in my opinion they are safe to apply. What I did basically boils down to two changes: 1. separate "concatenations", this is the first patch: @ref first/@ref second -> @ref first / @ref second`. 2. modify newlines, this is the second patch. As for the second patch, there are quite a lot of changes indeed, but 99% of them are almost automatic. To fix the build failure I had to do change something like 10-20 of the newlines, but this way some parts of the docs would use '\n' and some of them would use "
", so not very consistent, the problem would then appear sooner of later. So I decided to change all '\n' to "
". I quickly noticed that ~10% of the newlines are not needed - these were newlines that were before an empty line (at the end of paragraph) or before another doxygen paragraph (i.e. different type of section) or stuff like that. So this second change was executed like this: 1. Find all occurrences of following regex: "\\n\$" ('\n' at the end of line) in source files. Fortunately 100% of them were in doxygen comments, there were no occurrences in actual code. 2. If this newline is not needed - just delete it. 3. If this newline can be replaced with something else - do it (I remember only one case, where I changed "manual" implementation of an ordered list to a "automatic" ordered list, by just changing "1)" to "1." and so on). 4. Otherwise replace '\n' with "
". It took me 10 minutes to do it, so I wouldn't say this is huge, even though there are quite a few of such changes. I know that "
" is 4 characters and HTML while '\n' is C and just 2 characters - I think a doxygen problem (even if it turns out to be a bug and will disappear some time in the future) is a good justification to do it. There's also another way - it would be to ban manual newlines in doxygen comments. This would actually also be pretty simple and would just need a little reformatting of the text, using one of the methods for each of newlines: - splitting lines to paragraphs - changing lines to (un)ordered lists - merging lines into single paragraphs - ... There would be some visual changes and the patch would be bigger, but this would still be really simple changes only. Please reconsider (; Even if it turns out to be a bug, doxygen 1.8.15 will be here at least for a year and there is no guarantee that next version will behave differently.     _______________________________________________________ Reply to this item at:   _______________________________________________   Message sent via Savannah   https://savannah.nongnu.org/_______________________________________________ lwip-devel mailing list [hidden email] https://lists.nongnu.org/mailman/listinfo/lwip-devel