Documenting flashrom's guts
Hi list, There's several things regarding flashrom's structure that seem to be underdocumented (or *are* documented, but the information is extremely hard to find). It would be very helpful to have this information available somewhere easy to find, such as the Wiki. Some things that would greatly benefit from being documented are: - flashrom's layers: which layers there are, and how they interact with each other. - flashrom's structures: which structures there are, how they interact with each other, and how they "map" to layers. Surely there are more things that would benefit from being documented. Let's not discuss *who* is going to do what for now; first, let's collect information about these parts of flashrom. Best regards, Angel
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. -- Anastasia.
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 <aklm@chromium.org> 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.
-- Anastasia. _______________________________________________ flashrom mailing list -- flashrom@flashrom.org To unsubscribe send an email to flashrom-leave@flashrom.org
participants (3)
-
Anastasia Klimchuk -
Angel Pons -
Edward O'Callaghan