\include{doc} ignores EXAMPLE_PATH

[eseiler]

Describe the bug
Warning:

example/include/header.hpp:3: warning: \include{doc} file 'example/include/fragments/example.md' not found
example/include/header.hpp:6: warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 1)

And the content of the file is not included.

EXAMPLE_PATH doesn't seem to be checked for the included file, instead the base path of the file that calls \include is used.

example/
├── Doxyfile
├── doc
│   └── fragments
│       └── example.md
└── include
    └── header.hpp

With header.hpp:

/*!\brief A struct.
 * \details
 * \include{doc} fragments/example.md
 */
struct S{};

With example.md:

This is some documentation to be included.

And an otherwise default Doxyfile with:

-INPUT                  =
+INPUT                  = include/

-EXAMPLE_PATH           =
+EXAMPLE_PATH           = doc/

It also does not work if I put the md file into doc, remove the fragments directory, and use the absolute root path as EXAMPLE_PATH, and then try to include doc/....

Expected behavior
No warning, and content is included.

To Reproduce
example.tar.gz

Version
Persists on current master (c87ad3c)

Bisect:
Works: e73e0f9
Breaks: 7780d51

[albert-github]

This looks like to have the same / similar problem as investigated in #7688 (comment)

[eseiler]

This looks like to have the same / similar problem as investigated in #7688 (comment)

Indeed, didn't see the comments when checking commits/PRs for bisecting :)

I also noticed the second issue mentioned there (MD file starting with a header is not shown, except when it starts with a newline). Didn't include it here, because it also didn't work in the bisected versions.

[albert-github]

Regarding the EXAMPLE_PATH: Please verify if the commit (e8c5f55) fixes the problem for you.

@ doxygen
At the moment I get the impression that this is not yet the case though as I get the warnings:

.../example/include/header.hpp:3: warning: \include{doc} file 'D:/speeltuin/issue_10449/example/include/fragments/example.md' not found
.../example/include/header.hpp:6: warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 1)

[eseiler]

It doesn't quite fix the problem.

I get the same warning you described:

/dev/shm/example/include/header.hpp:3: warning: \include{doc} file '/dev/shm/example/include/fragments/example.md' not found
/dev/shm/example/include/header.hpp:6: warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 1)

When setting RECURSIVE = YES in the Doxyfile, I get

/dev/shm/example/include/header.hpp:3: warning: \include{doc} file 'fragments/example.md' could not be read

Replacing \include{doc} fragments/example.md with \include{doc} doc/fragments/example.md makes it work, independent of RECURSIVE = YES/NO.

---

However, the workaround of adding doc/ does not work if doxygen is being run inside a subdirectory.
This is what actually happens in the repository from which I derived the minimal example.

The warning is:

/dev/shm/example/include/header.hpp:3: warning: \include{doc} file 'doc/fragments/example.md' could not be read

Here is another test case, doxygen is called inside the test directory:

example
├── doc
│   └── fragments
│       └── example.md
├── include
│   └── header.hpp
└── test
    └── Doxyfile

example.md (same as in original test case)

This is some documentation to be included.

header.hpp (doc/ added)

/*!\brief A struct.
 * \details
 * \include{doc} doc/fragments/example.md
 */
struct S{};

Doxyfile (changed, diff to default)

-INPUT                  =
+INPUT                  = ../include

-RECURSIVE              = NO
+RECURSIVE              = YES

-EXAMPLE_PATH           =
+EXAMPLE_PATH           = ../doc

1.9.8 accepts both ../doc and .. as EXAMPLE_PATH.

In our projects, we use absolute paths.

example2.tar.gz

[doxygen]

@eseiler I think I found the problem. Please verify if the referenced commit indeed fixes the problem. Do not close the issue, this will be done automatically when the next official release is made.

[albert-github]

@doxygen I still get warnings like:

.../include/header.hpp:3: warning: \include{doc} file '.../include/fragments/example.md' not found
.../include/header.hpp:6: warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 1)

Example: example.tar.gz

Note: the second warning is also mentioned as note in the proposed pull request #10457

[eseiler]

@doxygen I still get warnings like:

.../include/header.hpp:3: warning: \include{doc} file '.../include/fragments/example.md' not found
.../include/header.hpp:6: warning: Reached end of file while still inside a (nested) comment. Nesting level 1 (probable line reference: 1)

Example: example.tar.gz

Note: the second warning is also mentioned as note in the proposed pull request #10457

It works with RECURSIVE = YES.

Since we use RECURSIVE = YES, our project builds again.

[albert-github]

I see that it works with RECURSIVE=YES though I'm not sure this is the right solution or this is by accident as when we look in the code we have:

\include{doc} fragments/example.md

and the setting:

EXAMPLE_PATH           = doc/

and the file example.md resides on the directory doc/fragments so I think that even without the RECURSIVE=YES` it should be possible to find the file.

[albert-github]

Interesting to see here also the behavior of the \include command.
In case of RECURSIVE=NO the \include fragments/example.md works as as expected and does not throw a warning.

[doxygen]

@albert-github It does indeed not make much sense to have different results for \include and \include{doc} for the same file. So I've now used the same routine for resolving the name for \include{doc} as was there for \include.

[albert-github]

Using the same procedure for \include{doc} and include definitely makes sense.
Have to do some testing to seen whether or not everything works now so as expected.

[doxygen]

@albert-github One more commit to relax the absolute path requirement.

[albert-github]

I get a warning during compilation:

...\src\util.cpp(3293): warning C4456: declaration of 'fi' hides previous local declaration
...\src\util.cpp(3281): note: see declaration of 'fi'

[doxygen]

@albert-github Somehow my compiler doesn't produce this warning. Should be fixed now.

[albert-github]

Indeed fixed, but the code like:

  bool found=false;
  if (!found)

will probably be flagged by sonarcloud or coverity as "code smell" as the if is a bit useless, I think leaving the block but removing the if would be better.

[doxygen]

I kept the redundant if with the idea that it makes it easier to add new sections and change the order of sections, without accidentally creating an unguarded section.

[albert-github]

I kept the redundant if with the idea that it makes it easier to add new sections and change the order of sections, without accidentally creating an unguarded section.

I think that that is a valid reason.