On Mon, Apr 18, 2022 at 18:50 Fujii Hironori via webkit-dev < webkit-dev@lists.webkit.org> wrote:
On Tue, Apr 19, 2022 at 6:55 AM Yusuke Suzuki via webkit-dev < webkit-dev@lists.webkit.org> wrote:
I think this is important. We are using commit message / ChangeLog as a document tied to the change, and we are writing very detailed description to make the intention / design of the change clear and making it as a good document when we read the change via git-blame, bisect, using that header, investigating how it works etc. To make / keep this commit message / ChangeLog helpful, we need review, and I think reviewing of these messages is critical to keep usefulness of them.
I don't think commit messages and ChangeLogs are the best place for technical descriptions. We use them because we don't have a better place.
libpas added the technical document in the repository in markdown.
https://github.com/WebKit/WebKit/blob/main/Source/bmalloc/libpas/Documentati...
This makes it possible to change code and update the document in a single commit, and get reviewed. markdown is better than plain text. Updated documents are more useful than the historical wiki pages. It'd be nice if more documents are migrated into the repository.
Documentation gets obsolete relatively quickly. Code is the source of truth. A lot of comments in WebKit are either outdated, incorrect, and/or misleading. Change logs describe a change and thereby a specific point in time of the repository and wouldn't carry the same issue. It's also particularly useful to be able to see why a given line of code was written. Was it an oversight? On purpose? Or perhaps the required behavior different then and now? It's impractical and unproductive to add such a comment on every line of our codebase, and that level of online comment will add so much clutter to the codebase and would make it harder to read the code. - R. Niwa -- - R. Niwa