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

[Dan Scally]

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


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