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

19343 diff mbox series

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.

Signed-off-by: Daniel Scally <dan.scally@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

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@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
>

Hi Jacopo

On 26/12/2023 10:51, Jacopo Mondi wrote:
> 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!


Agreed, but it wasn't my idea actually :)

>
>> Signed-off-by: Daniel Scally <dan.scally@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.


Sure, i can rewrite it into that vein.

>
>> +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 ?


I can pop the references inside the \if block below so that only the most relevant ones are 
mentioned at all.

>
>> +
>> +\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.


Okedokey

>
>> +
>> +\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// ?
And okedokey again.
>> +[reference pages](../internal-api-html/index.html) instead
>> +
>> +\endif
>> +*/
>> --
>> 2.34.1
>>