Improve API documentation

[n0y0nD]

This PR improves and cleans up the public API documentation.

I reorganized and structured the documentation comments above
the relevant function prototypes, clarified parameter and return
descriptions, and made the formatting more consistent with the
documentation style used in CUPS.

This is part of the ongoing work for issue #54 .

[tillkamppeter]

This information is still relevant, please do not remove it.

You can move it to the comment block at the top of the function though.

[tillkamppeter]

Please keep this "Note: ..." section. You can move it to the comment block at the top of the function.

[tillkamppeter]

All this information is still relevant, please do not remove it.

You can move it to the comment block at the top of the function though.

[tillkamppeter]

Do not remove "// Prototypes...".

Add an empty comment line before the comment you are adding here.

[tillkamppeter]

Priscill (@prisorue), this PR is ny volunteer contributor Nayanjyoti Das (@n0y0nD). Here you can see our libcupsfilters API documentation worked on and you can team up with Nayanjyoti, for example also reviewing his work, see how to proceed for API documentation and apply it to our other libraries, ...

[tillkamppeter]

Thanks for the inline documentation work.

Could you please not remove the longer, detailed comments which I have wrote up for some of the API functions. If they do not fit in for the automatic documentation generation, please put them into the manual part of the API documentation.

Please also tell when you are so far ready for the PR being merged.

Also the failing tests are not caused by your works. Other contributors are already working on them.

[prisorue]

@n0y0nD I sent you a DM via GChat with some questions.

@tillkamppeter I checked this PR. So far, what we need for API Docs are basically:

• Input parameters
• Output parameters
• Function description

We need to balance developer-friendly inline header references with high-level architectural guides. Considering that we already have annotations in the *.h files, we can use a lightweight pipeline that combines Doxygen (source extraction) with GitHub Pages & Actions to host and deploy the content. Hence, before moving forward, a couple of questions:
a. Have you considered using Doxygen or any other similar tool to extract information from the headers?
b. If a == yes, what's the current status and where can I find more information about the approach used to document APIs?

[tillkamppeter]

When I had developed libcupsfilters 2.x, libppd2.x, and pappl-retrofit, I have given header comments to the functions (at least the API functions), in the *.c files, as Michael Sweet does in CUPS. The header comments contain the descriptions and parameters of the functions. The syntax is for using the same documentation generator tool as for CUPS (seems something similar to Doxygen):

https://github.com/michaelrsweet/htmldoc

cpdb-libs and cpdb-backend-cups have comments formatted for another tool. Here we should create a script to convert the format to htmldoc.

We also need to check through all the code whether no header comments are missing or not matching the function's actual parameters.

In general, we can generate HTML, markdown, and other formats from this.

We should both generate documentation which gets installed locally by doing make install with the library's source code AND documentation to be browsed on our web site (and so also be covered by the site's search facility).

[tillkamppeter]

@n0y0nD Could you take care of the conflicts and make your work applying correctly to the current state of libcupsfilters

Also, as @prisorue says, we do not only need the generated (reference) documentation, also more around it, introducing into the structures and guiding the developer how to use the library.