| Summary: | [WPE] Mark "backend" parameters of web view constructors not nullable | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Product: | WebKit | Reporter: | Adrian Perez <aperez> | ||||||||
| Component: | WebKit API | Assignee: | Adrian Perez <aperez> | ||||||||
| Status: | RESOLVED FIXED | ||||||||||
| Severity: | Normal | CC: | cgarcia, mcatanzaro, mrobinson, webkit-bug-importer | ||||||||
| Priority: | P2 | Keywords: | InRadar | ||||||||
| Version: | WebKit Nightly Build | ||||||||||
| Hardware: | Unspecified | ||||||||||
| OS: | Unspecified | ||||||||||
| See Also: | https://bugs.webkit.org/show_bug.cgi?id=178901 | ||||||||||
| Attachments: |
|
||||||||||
|
Description
Adrian Perez
2022-04-04 06:11:30 PDT
Created attachment 456564 [details]
Patch
Comment on attachment 456564 [details] Patch View in context: https://bugs.webkit.org/attachment.cgi?id=456564&action=review > Source/WebKit/UIProcess/API/wpe/WebKitWebViewWPE.cpp:65 > + * @backend: (transfer full) (not nullable): the WPE view backend to use. Hrm. "WPE view backend" seems a bit more ambiguous here than [class@WebKitWebViewBackend]. Is there some reason to use phrases like this rather than the class name? (In reply to Martin Robinson from comment #2) > Comment on attachment 456564 [details] > Patch > > View in context: > https://bugs.webkit.org/attachment.cgi?id=456564&action=review > > > Source/WebKit/UIProcess/API/wpe/WebKitWebViewWPE.cpp:65 > > + * @backend: (transfer full) (not nullable): the WPE view backend to use. > > Hrm. "WPE view backend" seems a bit more ambiguous here than > [class@WebKitWebViewBackend]. Is there some reason to use phrases like this > rather than the class name? Yes: the documentation output already writes the type by itself, there is no need to repeat it every single time. You can find example output here: https://people.igalia.com/aperez/Documentation/wpe-webkit-1.1/ctor.WebView.new.html The documentation comment is expected to *describe* what each parameter is and/or does, not repeating the type, which the documentation generator already knows. Created attachment 456565 [details]
Screenshot of the generated documentation with patch applied
Hopefully this helps understand how it is unneeded to manually
repeat the type of parameters and returned values, given that
the documentation generator will anyway write them in the output
by itself :-)
(In reply to Adrian Perez from comment #3) > Yes: the documentation output already writes the type by itself, there is > no need to repeat it every single time. You can find example output here: > > > https://people.igalia.com/aperez/Documentation/wpe-webkit-1.1/ctor.WebView. > new.html > > The documentation comment is expected to *describe* what each parameter > is and/or does, not repeating the type, which the documentation generator > already knows. I think the issue is that a phrase like "WPE view backend" doesn't really describe what the parameter does, because it's more of less the type name with spaces in it. As an outsider to WPEWebKit, it is difficult to understand what purpose this parameter serves. It's even a little inaccurate in that a "WPE view backend" isn't the same as a WebKitWebViewBackend, which is a wrapper around a WPE view backend. Created attachment 456622 [details]
Patch v2
Now with (hopefully) better wording :)
Committed r292379 (249244@main): <https://commits.webkit.org/249244@main> All reviewed patches have been landed. Closing bug and clearing flags on attachment 456622 [details]. |