Closed Bug 1442429 Opened 2 years ago Closed 2 years ago

Correct the documentation for nsIBrowserSearchService::addEngineWithDetails

Categories

(Core :: Networking, enhancement)

enhancement
Not set

Tracking

()

RESOLVED FIXED
mozilla60
Tracking Status
firefox60 --- fixed

People

(Reporter: bytesized, Assigned: bytesized)

Details

Attachments

(1 file)

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
Attachment #8955323 - Flags: review?(mozilla)
Comment on attachment 8955323 [details]
Bug 1442429 - Correct the documentation for nsIBrowserSearchService::addEngineWithDetails

https://reviewboard.mozilla.org/r/224488/#review230448
Attachment #8955323 - Flags: review?(mozilla) → review+
Assignee: nobody → ksteuber
Pushed by ksteuber@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/cfc5d19e856f
Correct the documentation for nsIBrowserSearchService::addEngineWithDetails r=mkaply
https://hg.mozilla.org/mozilla-central/rev/cfc5d19e856f
Status: NEW → RESOLVED
Closed: 2 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla60
You need to log in before you can comment on or make changes to this bug.