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

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Wilfred
URL:
  <https://savannah.nongnu.org/bugs/?56004>

                 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:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

Wilfred
Follow-up Comment #1, bug #56004 (project lwip):

Care to provide a patch?

    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

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

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

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

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

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

    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

Wilfred
Follow-up Comment #5, bug #56004 (project lwip):

Local system is 1.8.14, Travis: 1.8.6

    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

Wilfred
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
   
<https://savannah.nongnu.org/file/0001-Fix-doxygen-ref-in-altcp.c.patch?file_id=46645>

File name: 0002-Fix-and-simplify-newlines-in-doxygen-documentation.patch
Size:27 KB
   
<https://savannah.nongnu.org/file/0002-Fix-and-simplify-newlines-in-doxygen-documentation.patch?file_id=46646>



    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

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


    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

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

    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel
Reply | Threaded
Open this post in threaded view
|

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

Wilfred
Update of bug #56004 (project lwip):

                  Status:                    None => Fixed                  
             Open/Closed:                    Open => Closed                

    _______________________________________________________

Follow-up Comment #9:

Agreed, I applied your patches. Thanks!

    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?56004>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/


_______________________________________________
lwip-devel mailing list
[hidden email]
https://lists.nongnu.org/mailman/listinfo/lwip-devel