Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Sat, 5 Feb 2022 23:39:45 +0100
From:   Tomasz =?UTF-8?B?V2FybmllxYLFgm8=?= <tomasz.warniello@gmail.com>
To:     corbet@lwn.net
Cc:     linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Tomasz =?UTF-8?B?V2FybmllxYLFgm8=?= <tomasz.warniello@gmail.com>
Subject: [RFC] scripts: kernel-doc: Major kernel-doc rework
Message-ID: <20220205233945.7a4d22d8@fuji.fritz.box>
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Precedence: bulk

This is in fact a release notification of a major kernel-doc script
refurbishment I have done. My work has reached a stage, which can be
considered a world sync point and here we are.

I'm not sending all the patches to the Linux mailing list, as I prefer
to check what you think before I emit about 500 emails.

I've parked the lot for you to inspect here:
https://salsa.debian.org/guest/kernel-doc

This also helps me report the bug fixes. See the issue tracker:
https://salsa.debian.org/guest/kernel-doc/-/issues

A FEW PRACTICAL WORDS

Before I move on, I'd like to ask you for support. I can't find a job -
neither as a junior, nor even part time. So if you find my effort
valuable and are able to, send me some Dollars, Euro or other Yen or
Ruble to my PayPal account linked with:

tomasz.warniello@gmail.com

If you have a job offer for me, the address stays the same. I consider
myself a general Linux assistant, in case you wonder.

Thank you.

BASIC INFO

The main area of my rework's focus is modularisation. The leading theme
is getting rid of the globals. In the meantime, smaller chunks of code
get assigned to packages, instance interfaces are built and wrap instance
variables, while helper functions land in their container functions,
various variables get lexicalised in their scopes, etc.

What is also done are countless simplifications, reductions, merges,
unifications, but also splits and duplications where logic and
architecture suggests so or requires.

The starting point for this rework is the official Linux tree commit
2a987e65025e2b79c6d453b78cb5985ac6e5eb26. It is also the base for all
tests performed throughout the process. (Except it changes slightly
with bug fixes.)

The initial fifteen patches are the POD series I published on the Kernel
mailing list. It was already version 3, which somehow got forgotten or
whatever happened to it. You can find it here:
https://lore.kernel.org/linux-doc/20220104015946.529524-1-tomasz.warniello@gmail.com/

One exception here is the copyright patch, which now is version 4.

The final, release version offers:
- ca. 20 bug fixes - big and small
- a few extra features
- no wild globals
- execution time not much worse than the original, despite the internal
  bureaucracy - in fact much better, though maybe not with single files

PATCH ERRATA

For the first ca. 200 patches, when I did indentation and spacing
corrections, I also simplified parentheses. Then I thought I'd better
cover this activity in patch descriptions. Correcting all the early ones
feels far beyond my powers.

PATCH MARKS

1. Enhancements
Patches marked with * at the end of the title contain changes that go
slightly against the master. I'm sometimes unsure if they're enhancements
or bug fixes.

2. Uncertainty
Patches marked with (?) at the of the title are those, which I consider
difficult to check. They may be ok, but should be examined with special
care.

SERIES GUIDE

The first patch in the repository contains the base, ie. the master
version of the script. Please let me know if I should have included
something essential like a license, etc. I've done my research and
came to the conclusion the script can move on its own. But...

The last patch contains this note and a few test scripts I used.

All the patches between them contain only changes to kernel-doc itself.
They are all signed-off.

TESTING

Initially it was chaotic with rst conclusions based on HTML builds and
with scant notes only in every some patch. But it soon got better and
more intelligent. I stated to inspect pure rst and included a note in
every patch unless no test was actually performed. It stayed so ever
after with light tests based on a 200 file sample and heavier tests
covering all available files.

The test reference is the master Linux commit, changing with bugfixes.

REUSE AND PORTING

The series is ready to be pulled by the Linux upstream at will. Of course
I can send it to the Linux mailing list - just let me know. The patches
are signed-off, patch-checked, and ready to go, the best of my knowledge.

That is - except for things like indentation, which is not worse than in
the master if you ask me, but it definitely is far from any claim of
correctness. Not in the conventional sense.

A few patches may undoubtedly be considered egoistic, like the Gedit
syntax highlight helper, or many of the indentation corrections. What can
I say? I needed them. Without them I would be fighting with an uncessant
swarm of tiny difficulties, and would quite likely never get to the end.

What else then? You might be interested in porting bug fixes, which may be
or may not be easy, depending on the case. You might also want to use my
version as an output reference. It's there for you as a whole and as parts.
It's up to you, so help yourselves as you please.

FINAL THOUGHTS

I could have used the POD space prepared for documentation and written
at least general summaries for all modules. But that's another adventure.
I need a break now.

There is still a lot to do around this script. parse_body is a noble warm up
candidate.