[v2,09/10] Documentation: mainpage: Make it easier to distinguish public and internal API

24338 diff mbox series

From: Stefan Klug <stefan.klug@ideasonboard.com>

It might be confusion to customers to see very similar looking doxygen
documentation with different content. Improve that by clearly stating
'public API' or 'internal API' on the main page.

Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
---
Changes since v1:

- Rename "libcamera Public-API reference" to "libcamera public API
  reference" (and same for the internal API)
---
 Documentation/mainpage.dox | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
> From: Stefan Klug <stefan.klug@ideasonboard.com>
> 
> It might be confusion to customers to see very similar looking doxygen
               ^
           confusing


> documentation with different content. Improve that by clearly stating
> 'public API' or 'internal API' on the main page.
> 
> Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> ---

Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>


> Changes since v1:
> 
> - Rename "libcamera Public-API reference" to "libcamera public API
>    reference" (and same for the internal API)
> ---
>   Documentation/mainpage.dox | 6 +++++-
>   1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/mainpage.dox b/Documentation/mainpage.dox
> index cbee9bab12ec..fae99f28f1af 100644
> --- a/Documentation/mainpage.dox
> +++ b/Documentation/mainpage.dox
> @@ -1,5 +1,9 @@
>   /**
> -\mainpage libcamera API reference
> +\if internal
> +\mainpage libcamera internal API reference
> +\else
> +\mainpage libcamera public API reference
> +\endif
>   
>   Welcome to the API reference for <a href="https://libcamera.org/">libcamera</a>,
>   a complex camera support library for Linux, Android and ChromeOS. These pages

On Fri, Sep 12, 2025 at 11:00:03AM +0200, Barnabás Pőcze wrote:
> 2025. 09. 12. 1:01 keltezéssel, Laurent Pinchart írta:
> > From: Stefan Klug <stefan.klug@ideasonboard.com>
> > 
> > It might be confusion to customers to see very similar looking doxygen
>                ^
>            confusing

I'll replace "customers" to "consumers" too.

> > documentation with different content. Improve that by clearly stating
> > 'public API' or 'internal API' on the main page.
> > 
> > Signed-off-by: Stefan Klug <stefan.klug@ideasonboard.com>
> > Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
> > ---
> 
> Reviewed-by: Barnabás Pőcze <barnabas.pocze@ideasonboard.com>
> 
> > Changes since v1:
> > 
> > - Rename "libcamera Public-API reference" to "libcamera public API
> >    reference" (and same for the internal API)
> > ---
> >   Documentation/mainpage.dox | 6 +++++-
> >   1 file changed, 5 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/mainpage.dox b/Documentation/mainpage.dox
> > index cbee9bab12ec..fae99f28f1af 100644
> > --- a/Documentation/mainpage.dox
> > +++ b/Documentation/mainpage.dox
> > @@ -1,5 +1,9 @@
> >   /**
> > -\mainpage libcamera API reference
> > +\if internal
> > +\mainpage libcamera internal API reference
> > +\else
> > +\mainpage libcamera public API reference
> > +\endif
> >   
> >   Welcome to the API reference for <a href="https://libcamera.org/">libcamera</a>,
> >   a complex camera support library for Linux, Android and ChromeOS. These pages