1442429 - Correct the documentation for nsIBrowserSearchService::addEngineWithDetails

Status: RESOLVED FIXED

(Core :: Networking, enhancement)

Description

[Robin Steuber (they/them) [:bytesized]]

The documentation for nsIBrowserSearchService::addEngineWithDetails[1] incorrectly identifies that argument 6 as the "url" argument with the description "The URL to which search queries should be sent. Must not be null."

Then, just below, it gives this example of the parameters-via-object syntax:

Services.search.addEngineWithDetails("Example engine", {
    template: "http://example.com/?search={searchTerms}",
    description: "Example search engine description",
    suggestURL: http://example.com/?suggest={searchTerms},
});

Clearly these two bits of documentation are incompatible since the second passes no "url" argument. Additionally, there appears to be no parameter called "template". I took a look at the implementation[2], which calls the 6th argument "template". After following the use of that argument around a bit, I believe that it is eventually passed to the ParamSubstitution function[3], which is documented as implementing an "OpenSearch parameter substitution".

I would like to change the documentation to reflect that argument 6 of nsIBrowserSearchService::addEngineWithDetails is called "template" and the input should be a URL that will be subjected to OpenSearch parameter substitution.

[1] https://searchfox.org/mozilla-central/rev/769222fadff46164f8cc0dc7a0bae5a60dc2f335/netwerk/base/nsIBrowserSearchService.idl#352-354
[2] https://searchfox.org/mozilla-central/rev/769222fadff46164f8cc0dc7a0bae5a60dc2f335/toolkit/components/search/nsSearchService.js
[3] https://searchfox.org/mozilla-central/rev/769222fadff46164f8cc0dc7a0bae5a60dc2f335/toolkit/components/search/nsSearchService.js#976

Comment 1

[Robin Steuber (they/them) [:bytesized]]

Attachment: Bug 1442429 - Correct the documentation for nsIBrowserSearchService::addEngineWithDetails

Review commit: https://reviewboard.mozilla.org/r/224488/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/224488/

Comment 2

[Mike Kaply [:mkaply]]

Comment on attachment 8955323 [details]
Bug 1442429 - Correct the documentation for nsIBrowserSearchService::addEngineWithDetails

https://reviewboard.mozilla.org/r/224488/#review230448

Comment 3

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/cfc5d19e856f
Correct the documentation for nsIBrowserSearchService::addEngineWithDetails r=mkaply

Comment 4

[Andreea Pavel [:apavel]]

https://hg.mozilla.org/mozilla-central/rev/cfc5d19e856f