On Tue, Aug 2, 2016 at 12:28 PM, Frank Rowand <frowand.list@xxxxxxxxx> wrote: > Hi Rob, > > I've been working on cleaning up the docbook function documentation > in the device tree files. The resulting patches could interfere with > code patches, so I want to figure out how to structure the documentation > patches to avoid that. I would like your opinion and suggestions on > the subject. > > First premise: this set of documentation changes is a second class > citizen compared to code changes. Any patch from this set can be > dropped any time it interferes with a code patch. > > I started the project with the simple intent of fixing what was > clearly broken. > - fix syntax errors > - fix mismatches between actual function arguments vs docbook > list of function arguments > - fix mismatches between function return type (void vs anything) and > values vs docbook return types and values > - fix factually incorrect descriptions of what the function does > > When I was making those changes, I found also found documentation > that was somewhat cryptic or otherwise hard to understand. I also > found that the description of the same item was described in a > wide variety of ways in different docbook headers. I made an > effort to also clean that up. > > The result was a large patch series (that was not totally complete): > > 15 files changed, 1414 insertions(+), 730 deletions(-) All in drivers/of and related headers? > plus around 150 lines of change to docbook files so that > the device tree man pages would be created. I did not > add any other significant docbook documentation of device tree. > > There are at least a couple of approaches I could take for > submitting patches (and would be glad to hear of any other > approach that I did not think of): > > 1) The big ugly patchset referenced above, one patch per > file. > pro: exposes what changes were made to each function > documentation header > con: very dense and not very readable > con: the mechanical corrections create a lot of noise if > the reviewer wants to view actual content changes > con: probably more likely to conflict with code patches > in a way that is not easily fixed This is fine with me. Let's not over complicate things. There aren't that many changes typically in a cycle, so we can deal with it. I'd expect most changes would not collide as docbook comments and code changes are separated somewhat. I'd like a git branch for this. I'll keep it separate until -rc6 or so and then you can rebase things then if merging becomes a problem. Or we can drop any problematic patches. > 2) Split method 1 into stages (one patch per file for each stage). > Examples of some possible stages are: > - white space fixes > - syntax fixes > - incorrect argument list fixes > - incorrect return type fixes > - incorrect return value fixes > - incorrect behavior description fixes > - confusing behavior description fixes > pro: it would be easier to review patches for many of the stages > con: a lot more patches > con: maybe difficult to handle conflicts with code patches > con: maybe difficult to rework patches for review comments (changes > for an earlier stage are likely to impact a patch for a later > stage) > > 3) Do one patch series to remove all docbook function header documentation. > Do a second patch series to add the updated docbook function header > documentation. For each of the two series, one patch per file. > pro: the patches are much easier to read > pro: it might be easier to resolve conflicts with source patches > (either you dropping a few hunks or me redoing the docbook patch > to remove the conflict) > con: the actual changes to what the documentation says are not visible > > My current version of the patches is against 4.7-rc2. I will have to update > this to 4.7 or 4.8-rc1 (I would assume that 4.8-rc1 would make more sense). You've followed all the documentation changes for 4.8 using Sphinx, right? Is this going to impact your work? Rob -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
