[PATCH v1] Documentation: Fix `INCLUDE_PATH` doxygen configuration option

[Kieran Bingham]

Quoting Barnabás Pőcze (2025-05-26 14:25:08)
> 2025. 05. 26. 14:19 keltezéssel, Kieran Bingham írta:
> > Quoting Barnabás Pőcze (2025-05-26 13:03:55)
> >> libcamera header files should be included using the `libcamera/...` prefix.
> >> However, `INCLUDE_PATH` is currently set to `@TOP_SRCDIR@/include/libcamera`
> >> meaning that doxygen, when encountering `libcamera/x.h`, will try to open
> >> `@TOP_SRCDIR@/include/libcamera/libcamera/x.h`, which is not the correct
> >> path.
> >>
> >> Fix that by using `@TOP_{BUILD,SRC}DIR@/include`. This removes the extra
> >> `libcamera` component from the path and adds the corresponding directory
> >> from the build directory as well since that is an implicit include
> >> directory added by meson.
> >>
> >> Signed-off-by: Barnabás Pőcze <barnabas.pocze at ideasonboard.com>
> > 
> > This sounds very reasonable - I wonder when this crept in. I recall it
> > was a long time ago that we decided to keep libcamera headers under the
> > "/libcamera/*" include hierarchy - so I wonder if this was missed back
> > then or added since.
> > 
> > Anyway - it won't matter much - and I believe this sounds right.
> > 
> > Is there anything in the output doxygen that this fixes or that can
> > demonstrate doxygen is now doing the right thing that was missing
> > before?
> 
> You can see the difference if you run `doxygen -d preprocessor ...`, e.g.
> 
>    #include libcamera/base/bound_method.h: already processed! skipping...
>    #include libcamera/base/message.h: parsing...
>      #include atomic: not found! skipping...
>      #include libcamera/base/private.h: parsing...
>      #include libcamera/base/bound_method.h: already processed! skipping...
> 
> vs.
> 
>    #include libcamera/base/bound_method.h: already processed! skipping...
>    #include libcamera/base/message.h: not found! skipping...
> 
> 
> I don't believe it changes anything in practice, or at least I have not
> noticed any changes. But I thought it's better to be correct even if it
> does not really do anything.

I agree, thanks for the insights above.

--
Kieran


> 
> 
> Regards,
> Barnabás Pőcze
> 
> 
> > 
> > Either way, I'd still give this an ack...
> > 
> > Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> > 
> >> ---
> >>   Documentation/Doxyfile-common.in | 3 ++-
> >>   1 file changed, 2 insertions(+), 1 deletion(-)
> >>
> >> diff --git a/Documentation/Doxyfile-common.in b/Documentation/Doxyfile-common.in
> >> index 045c19dd6..58afea1cd 100644
> >> --- a/Documentation/Doxyfile-common.in
> >> +++ b/Documentation/Doxyfile-common.in
> >> @@ -57,7 +57,8 @@ GENERATE_LATEX         = NO
> >>   MACRO_EXPANSION        = YES
> >>   EXPAND_ONLY_PREDEF     = YES
> >>   
> >> -INCLUDE_PATH           = "@TOP_SRCDIR@/include/libcamera"
> >> +INCLUDE_PATH           = "@TOP_BUILDDIR@/include" \
> >> +                         "@TOP_SRCDIR@/include"
> >>   INCLUDE_FILE_PATTERNS  = *.h
> >>   
> >>   IMAGE_PATH             = "@TOP_SRCDIR@/Documentation/images"
> >> -- 
> >> 2.49.0
> >>
>