[webkit-reviews] review requested: [Bug 226662] [GTK] Replace gtk-doc with gi-docgen : [Attachment 455242] The “only missing ChangeLogs and doc-comments in CMake modules” patch

[bugzilla-daemon at webkit.org]

Adrian Perez <aperez at igalia.com> has asked  for review:
Bug 226662: [GTK] Replace gtk-doc with gi-docgen
https://bugs.webkit.org/show_bug.cgi?id=226662

Attachment 455242: The “only missing ChangeLogs and doc-comments in CMake
modules” patch

https://bugs.webkit.org/attachment.cgi?id=455242&action=review




--- Comment #17 from Adrian Perez <aperez at igalia.com> ---
Created attachment 455242

  --> https://bugs.webkit.org/attachment.cgi?id=455242&action=review

The “only missing ChangeLogs and doc-comments in CMake modules” patch


- Both GTK and WPE ports correctly generate .gir and .typelib files
  using rules added by FindGI.cmake, and documentation using rules
  added by FindGIDocgen.cmake \o/

- Using the documentation check targets (i.e. “doc-check-all”) passes
  checks for JSC, there are a few warnings for WebKit, and a bunch of
  warnings for the WebExtension documentation.

- I did most of the grunt work for the first two to pass checks (add
  brief descriptions where missing, fix typos in symbol names, stop
  using “SECTION:Foo”, etc.) but considering that the style encouraged
  by gi-docgen is different from that of gtk-doc it would be a good
  thing to comb over the documentation in follow-up patches to do
  editorial improvements.

- While not warnings/errors, it would be still good to add some missing
  annotations, like the ones that associate properties with their setter
  and getter functions.

- Also, linking between symbols, code examples, and a few other things
  ares done a bit differently with gi-docgen, which embraces more usage
  of Markdown.

- With gi-docgen we can add Markdown documents to be integrated into
  the “Additional Documentation” area of the resulting output. For
  example in GTK4: https://docs.gtk.org/gtk4/#extra - it would be good
  to add an introduction/overview and some tutorial(s), and a document
  with the list of environment variables that affect operation. We can
  have a different set of files for each port.

All the improvements suggested above could be done in follow-up patches,
I think.