fixing the mac80211 documentation problem

fixing the mac80211 documentation problem

[Johannes Berg]

[-- Attachment #1: Type: text/plain, Size: 2116 bytes --]

Hi,

Previously I've always tried to document things in mac80211, and
recently I posted a list of driver requirements. Now when digging
through the HT code, I cannot even document driver requirements because
it's not really clear even to me what they are---and I just refactored
the code.

But it's not just HT, also the new rate control API is probably not
documented well enough (nbd has promised clarification though) and
possibly more I can't think of right now (like the unimplemented mesh
security, ...)

I think the process has gotten out of hand. It might be good for you,
but I can't be cleaning up mac80211 forever, this needs to stop at the
original code we "inherited", new code needs to be documented better.
I've also seen promises for documentation to be posted after the patches
go in, but so far those have been empty promises.

I take all the blame here for naively believing such promises would be
followed up on, trusting people too much and accepting code without
fully understanding it. Why did I even get this role?

Therefore, I'm inclined to require (if I get to have any influence on
this) all significant code contributions to mac80211, especially if they
affect the driver API, to be _preceded_ by design documentation.

Such documentation would consist of the documentation that will become
part of the mac80211 header file (driver and rate control API), an
explanation of why the driver API needs to be changed, how it affects
existing drivers, which standard it is based on and why we need to
implement it. Additionally, it should cover thoughts about how this
affects the various modes mac80211 can operate in (AP, STA, IBSS, MESH,
WDS, ...); if it's not implemented for all modes it should come with an
explanation of how such implementations would be possible in the future
should they become necessary.

I'm not sure how to actually collect this documentation, parts of it
(like the "how to implement feature X we have in STA mode for AP mode")
certainly should be part of the kernel tree, other things need not be.

Comments?

johannes

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 836 bytes --]