Clarify confusing properties
Background
The documentation refers to various properties in either ambiguous or misleading ways. Therefore we should clarify the documentation or rename them:
-
FilterMatchInfo
- The property names are too generic and can cause naming conflicts (e.g. with "info" module). For example,
details
is an appropriate name for the request details in the context of awebRequest.onBeforeRequest
listener, but not in the context ofewe.reporting.onFilterMatch
, where it's unclear what the difference is betweendetails
andinfo
just by looking at their names. See also confusion around types in #99 (closed).
- The property names are too generic and can cause naming conflicts (e.g. with "info" module). For example,
-
FirstRunInfo
-
subscriptionsFirstRun
: It's not clear whether the description refers to only downloadable subscriptions or also special subscriptions (thereby implying whether custom filter exist). - It's difficult to use those properties in conditions due to their vague names. They also lead to double negation when we use them to check for preexisting data, because they indicate whether it doesn't exist.
-
-
Subscription
-
downloadable
: Not sorted alphabetically, which makes it easier to miss while skimming through the documentation.
-
I also noticed that the README still links to eyeo/adblockplus/webext-sdk. It's not causing any problems, but it could be fixed as part of this issue, if we're already working on cleaning up the documentation.
Use case
Being able to understand the purpose and meaning of properties that are exposed by the SDK via its API.
What to change
Clarify the documentation for the above mentioned properties.
Suggested change
Update the documentation as follows
-
FilterMatchInfo
- Rename
details
property torequest
. - Rename
info
property tomatchInfo
.- Rename
info.matchingMethod
property tomatchInfo.method
- Rename
- Rename
-
FirstRunInfo
- Clarify that
subscriptionsFirstRun
property also considers whether custom filters exist. - Rename and negate
subscriptionsFirstRun
tofoundSubscriptions
. - Rename and negate
storageFirstRun
tofoundStorage
.
- Clarify that
-
Subscription
- Fix alphabetical order of properties.
Edited by Thomas Greiner