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

[Freddie Chopin]

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: address@hidden first/@ref
second` -> address@hidden 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/