buglwIP - A Lightweight TCP/IP stack - Bugs: bug #56004, Cannot build doxygen documentation...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

bug #56004: Cannot build doxygen documentation due to unresolved references

Submitter:  Freddie Chopin <freddie_chopin>
Submitted:  Tue 26 Mar 2019 11:25:32 AM UTC
   
 
Category:  Documentation Severity:  3 - Normal
Item Group:  Compiler Warning Status:  Fixed
Privacy:  Public Assigned to:  None
Open/Closed:  Closed Planned Release:  None
lwIP version:  git head

Jump to the original submission

Thu 28 Mar 2019 07:19:31 AM UTC, comment #9: 

Agreed, I applied your patches. Thanks!

Dirk Ziegelmeier <dziegel>
Group administrator
Wed 27 Mar 2019 07:52:34 AM UTC, comment #8: 


> 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 "<br>", so not very consistent, the problem would then appear sooner of later. So I decided to change all '\n' to "<br>". 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 "<br>".

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 "<br>" 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.

Freddie Chopin <freddie_chopin>
Wed 27 Mar 2019 06:47:31 AM UTC, comment #7: 

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 <br>: 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 :-(

Dirk Ziegelmeier <dziegel>
Group administrator
Tue 26 Mar 2019 04:37:53 PM UTC, comment #6: 

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)

Freddie Chopin <freddie_chopin>
Tue 26 Mar 2019 02:40:04 PM UTC, comment #5: 

Local system is 1.8.14, Travis: 1.8.6

Dirk Ziegelmeier <dziegel>
Group administrator
Tue 26 Mar 2019 11:52:11 AM UTC, comment #4: 


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

So 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 (;

Freddie Chopin <freddie_chopin>
Tue 26 Mar 2019 11:38:45 AM UTC, comment #3: 

I think the fix is ok. (the problem doesn't happen with my local doxygen version and the one on the Travis CI server)

Dirk Ziegelmeier <dziegel>
Group administrator
Tue 26 Mar 2019 11:36:55 AM UTC, comment #2: 


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

Freddie Chopin <freddie_chopin>
Tue 26 Mar 2019 11:29:27 AM UTC, comment #1: 

Care to provide a patch?

Simon Goldschmidt <goldsimon>
Group administrator
Tue 26 Mar 2019 11:25:32 AM UTC, original submission:  

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

Freddie Chopin <freddie_chopin>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attached Files
file #46645:  0001-Fix-doxygen-ref-in-altcp.c.patch added by freddie_chopin (2KiB - text/x-patch - patches to fix the problem with doxygen 1.8.15)
file #46646:  0002-Fix-and-simplify-newlines-in-doxygen-documentation.patch added by freddie_chopin (28KiB - text/x-patch - patches to fix the problem with doxygen 1.8.15)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by dziegel (Posted a comment)
  • -email is unavailable- added by goldsimon (Posted a comment)
  • -email is unavailable- added by freddie_chopin (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    Follow 4 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2019-03-28 dziegel StatusNone Fixed
        Open/ClosedOpen Closed
    2019-03-26 freddie_chopin Attached File- Added 0001-Fix-doxygen-ref-in-altcp.c.patch, #46645
        Attached File- Added 0002-Fix-and-simplify-newlines-in-doxygen-documentation.patch, #46646

    Back to the top

    Powered by Savane 3.13-d3ae.
    Corresponding source code