[libcamera-devel] [PATCH] libcamera: Documentation: Improve doxygen main page

[Jacopo Mondi]

Hi Dan

On Fri, Dec 22, 2023 at 05:04:49PM +0000, Daniel Scally via libcamera-devel wrote:
> The "Main Page" of the doxygen generated API reference is currently
> totally empty. Expand it with some introductory text along with links
> to the developer's guide, application developer's guide and the
> pipeline and IPA module writer's guides.
>
> Provide an easy link to switch between the reduced public reference
> pages and the more complete internal ones.

Good idea!

>
> Signed-off-by: Daniel Scally <dan.scally at ideasonboard.com>
> ---
> This patch depends on "[PATCH 2/2] libcamera: Documentation: Split public/private documentation"
>
>  Documentation/Doxyfile.in   |  6 ++++--
>  Documentation/libcamera.dox | 33 +++++++++++++++++++++++++++++++++
>  2 files changed, 37 insertions(+), 2 deletions(-)
>  create mode 100644 Documentation/libcamera.dox
>
> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in
> index 6689ace1..1c6412ed 100644
> --- a/Documentation/Doxyfile.in
> +++ b/Documentation/Doxyfile.in
> @@ -21,7 +21,8 @@ CASE_SENSE_NAMES       = YES
>
>  QUIET                  = YES
>
> -INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
> +INPUT                  = "@TOP_SRCDIR@/Documentation" \
> +                         "@TOP_SRCDIR@/include/libcamera" \
>                           "@TOP_SRCDIR@/src/ipa/ipu3" \
>                           "@TOP_SRCDIR@/src/ipa/libipa" \
>                           "@TOP_SRCDIR@/src/libcamera" \
> @@ -30,7 +31,8 @@ INPUT                  = "@TOP_SRCDIR@/include/libcamera" \
>
>  FILE_PATTERNS          = *.c \
>                           *.cpp \
> -                         *.h
> +                         *.h \
> +                         *.dox
>
>  RECURSIVE              = YES
>
> diff --git a/Documentation/libcamera.dox b/Documentation/libcamera.dox
> new file mode 100644
> index 00000000..c3101739
> --- /dev/null
> +++ b/Documentation/libcamera.dox
> @@ -0,0 +1,33 @@
> +/**
> +\mainpage libcamera API reference
> +
> +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 do

> +not explain how to use libcamera to consume data from camera sensors in your
> +application, nor how to add support to the library for your hardware. There is

I would rather explain what this page is about than what is not :)

Like mentioning that these pages are the API refenence generated from
the source and for a more generic introduction to the libcamera
high-level concepts and development mode the developer's guide is
likely a better place where to start from.

> +documentation available to detail how to achieve those things in detail, which
> +may be a better first contact with libcamera as a developer. As a starting
> +point we recommend the [developer's guide](../html/guides/introduction.html).
> +
> +As a follow-on to the developer's guide, if you wish add support for a new
> +platform the [pipeline handler writer's guide](../html/guides/pipeline-handler.html)
> +and the [ipa module writer's guide](../html/guides/ipa.html) should be helpful.
> +Alternatively if you are an application developer seeking to use libcamera within
> +your work the [application developer's guide](../html/guides/application-developer.html)
> +gives an overview on how to achieve that.

Should we split the guides into 'platform' and 'applications'
developers like it has been done for the API ? Or simply mention we
have guides and list all of them ?

> +
> +\if internal
> +
> +If you are an application developer seeking to use libcamera with your program
> +then you may find it useful to use the [reduced version](../api-html/index.html)
> +of the API reference pages instead, which excludes library objects if they are
> +intended for internal use only.

Well, to an app developer this is not 'reduced' but it's all they
need/want. So I would not use the term "application developer API" and
do not say they excludes anything but simply that only the public part
of the API is documented.

> +
> +\else
> +
> +If you are a developer seeking to add support for your hardware to the library
> +or make other improvements, you should switch to the more complete internal API

s/more complete// ?

> +[reference pages](../internal-api-html/index.html) instead
> +
> +\endif
> +*/
> --
> 2.34.1
>