[flashrom] Re: Documenting flashrom's guts

[Edward O'Callaghan]

It's a good plan to get the code more documented, possibly it is a good
idea to target interfaces between layers with some helpful Doxygen comments.

I see some issues down this line of thought however in that there are still
many places where flashrom has half baked layers or plainly incorrectly
situated ones such as programmer delay as the most recent example.
Documenting may help reveal the truth but it can also solidify
bad/incorrect code. Therefore it is worth keeping a flexible mind while
broaching the documentation of each layer of if it is even actually correct.

One possible tactic to make some headway with this, rather large effort, is
to divide and conquer it by having folks working on commits towards a
specific subsystem/layer [sic. unit-tests, flashchips, programmer struct]
follow up with commits that add some Doxygen comments at the boundary
points of this layer/subsystem.

Another project is to ensure we expose this documentation in a up to date
manner which fits into having a fresh, fun website that indexes the code
comments so the documentation is actually well maintained and current.

Cheers,
Edward.

On Tue, 8 Nov 2022 at 15:20, Anastasia Klimchuk  wrote:
> Hello,
>
> Great idea, I fully agree with documenting layers and structures! I
> also thought maybe in addition to that (as a second section) we could
> document how to do things? From the point of view of a developer who
> wants to contribute to flashrom.
>
> For example:
> how to add a programmer
> how to add a unit test
> how to add a command line argument
> how to add a flashchip (this info exists, although I am not sure that
> the long numbered list is well placed in the middle of Dev guidelines
>
> https://www.flashrom.org/Development_Guidelines#Adding/reviewing_a_new_flash...
> )
> how to modify libflashrom API and why not to do this
> what level of testing we expect for patches
> etc
>
> And all of that in the aspect of which layers/structures should the
> change involve.
>
> The goal (in my head) is not to give full instructions on every
> possible change of flashrom code, not at all. Rather, I am thinking to
> observe which kind of changes contributors do most often, and to add
> documentation that a diligent contributor can read before sending a
> patch.