Developer documentation for libcupsfilters2 API needed

[tillkamppeter]

We have recently released the second generation of cups-filters which especially also contains the second generation of libcupsfilters (this repository).

This also includes that libcupsfilters2 provides a new API which needs to get documented, to allow everyone to easily use the resources of this library which are the hard work of many people during the last 20+ years. Especially also the old libcupsfilters1 API did not get documented at all which makes the new one even more important to get documented.

At OpenPrinting we want to reach a common documentation standard on all our repositories. Example for this is our CUPS repository, where we have API documentation based on appropriately formatted comments in the C code (assembled by CodeDoc) plus manually created introduction and examples.

This we also want to do with the developer documentation of our other libraries, including libcupsfilters.

Most of the API functions and data types of libcupsfilters2 already have he comments needed for auto-generation of API documentation, but some can be missing and also some improvement here and there could be needed. We also ned the manual part, introduction and examples to be written and everything assembled during the build process of the package.

See also our talk about our documentation plans from our micro-conference on Linux Plumbers 2022: slides. video

[andoriyaprashant]

Hello @tillkamppeter
I'd like to work on this issue. Could you please assign it to me
Thanks

[tillkamppeter]

Sorry for the late reply, I have traveled back from Jaipur.

@andoriyaprashant thank you very much for your interest in this issue. Up to now nobody else has worked on it and so feel free to start on this task.

I have also listed it in Canonical's Open Documentation Academy:

canonical/open-documentation-academy#74

Here somebody else showed interest but did not show a sign to have started on it. So I suggest for now that you work on it and if that person comes back, we can share the work or one of you will do another library, like libppd or pappl-retrofit.

Also, in the Open DFocumentation Academy you can get help and mentorship from Canonical's Documentation Team, especially they have a video meeting for Q&A every Friday.

More about the Open Documentation Academy:
https://discourse.ubuntu.com/t/39615
https://github.com/canonical/open-documentation-academy

Now to the documentation task itself:

I hope you have already watched/read the talk/discussion about our documentation plans linked in the initial description of this issue and also had a look into the CodeDoc tool.

If you are already familiar with auto-documentation systems of libraries (this is for the developer documentation only, user and admin documentation is always written manually) you will quickly familiarize with the description header comments at the beginning of the code of each function and the processing utility CodeDoc.

Your task will not only be running the utility, but also completing the missing or too short header comments, also correcting the formatting depending on what the utility spits out, ... Also the developer documentation will need some introductory text which also needs to get created manually.

As an example you should have a look into the documentation of CUPS ("cups" repo at OpenPrinting, libcups API, programmer's manual).

You can also ask me at any time about the content, how things work in libcupsfilters, what is the general purpose, ...

Are you participating in the weekly Office Hours meeting of the Documentation Academy?

And here is a short list of the podcasts and videos where I am talking/got interviewed and a quick introduction into OpenPrinting.

I am also blogging once a month, the OpenPrinting News. I will ask you every month for a short write-up what you have done, to mention your work in the News.

Let us have a great collaboration!

[tillkamppeter]

Let us do all further discussion on canonical/open-documentation-academy#74 as there also the other person who has stepped up for this task is discussing it and also the folks from Canonical are reading. There we can share the work and one of you can either opt for further libraries at OpenPrinting or for further documentation types (see Diataxis)

• Reference (this is what CodeDoc and other library documentation tools do)
• Tutorial (this is to teach to a beginner how to use the software, like my workshops about Snap)
• How-To (Step-by-step instructions)
• Explanation (Why and how does this actually work?)

and audiences:

• Programmer/developer
• Administrator
• User