OpenPrinting: Developer documentation for libcupsfilters2 API needed

[tillkamppeter]

This is a manual copy of libcupsfilters issue #54. As long as issues #70 and #71 are not solved this is the only way to go.

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

[ScubyG]

I would be interested in adopting this issue and roughly estimate to complete it by end of September 2024.

I discovered the Open Documentation Academy via Late Night Linux, Ep 294

[tillkamppeter]

Hi @ScubyG ,

first, sorry for the late reply. Today/tomorrow is Feature Freeze for Ubuntu 24.10, therefore I had to finish and upload a lot of things.

You are highly welcome to do the task which I have put up here.

I hope you have already watched/read the talk/discussion about our documentation plans 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?

Are you listening to Late Night Linux regularly? It was one of the Linux podcasts where I got first mentioned, after the Ubuntu Summit 2022. But there I got also mentioned in further content.

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!

[ScubyG]

Hi @ScubyG ,

first, sorry for the late reply. Today/tomorrow is Feature Freeze for Ubuntu 24.10, therefore I had to finish and upload a lot of things.

You are highly welcome to do the task which I have put up here.

I hope you have already watched/read the talk/discussion about our documentation plans 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?

Are you listening to Late Night Linux regularly? It was one of the Linux podcasts where I got first mentioned, after the Ubuntu Summit 2022. But there I got also mentioned in further content.

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!

Not a problem at all, thank you for the reply.

I'm currently watching all of the Open Documentation Hour sessions and will join future ones when time permits, otherwise watch the recordings.

Regarding the CodeDoc tool, I have deployed it to test on one of my repos and learn more about this tool, I have previously utilised Asciidoc so have some learning to do here.

I'm a regular listener to Late Night Linux and podcasts from Jupiter Broadcasting, TuxDigital including some others (I endure an 8 hour drive commuting each week!) and have RSS subscribed to your blog posts.

Hopefully I can get up to speed them make some progress as documentation is a blocker in many cases when it comes to software, especially FOSS.

Thanks again and I look forward to working with you.

[tillkamppeter]

@ScubyG Are you ScubyGB on Mastodon?

[ScubyG]

@ScubyG Are you ScubyGB on Mastodon?
Yes, I can be found here >
@b1rdy@mastodon.social

[tillkamppeter]

@ScubyG How are things going, did you already start working on this issue?

[ScubyG]

I am still reading up on where to start with this and can now see why it is a size 8 project.

I am happy if there is someone else with far more knowledge than I to take the lead, but I would be interested to see how they do it.

[tillkamppeter]

@ScubyG any progress?

[hifron]

Maybe there should be https://libcupsfilters2.readthedocs.io/ man page

there is also GNOME components and GNOME contains also some apps like DevHelp which is GNOME API app. And there is also some Intro into GNOME libs development with handbook with also GNOME Desktop Discourse forum but Ubuntu also make today switch from ubuntuforums.org to make their Ubuntu Desktop Discourse also support page with linking from original ubuntuforums.org to specific part of Discourse (and like some Printing Section or API Section possible) but Ubuntu has also its Products Docs.

If DevHelp installed then there is need for gnome-devel-docs but maybe other GNOME libs and if some package installed and directories made filled, then also some CUPS libs API possible in DevHelp API browser application and if make some suggestions to gnome-devel stack than also apps like GNOME Builder could have access to such API because its maybe the same as DevHelp stack

There is also Debian admin handbook

[tillkamppeter]

I will not adopt readthedocs.io for OpenPrinting, as its free-of-charge plan presents the documentation with ads and also I cannot get access by an organization/a team, only by a single person, not being able to delegate tasks. Even using GitHub login is reserved to paid plans.