Document the resource database

[jspenguin2017]

The current resource database is really difficult to navigate and almost nothing is documented.

There are two types of resources: ones that are designed for one or a few specific websites, and ones that could apply to all websites. As of now, they are all mixed together, and it's really difficult to find the resource you want unless you have memorized them.

From this issue, it seems that no one beside gorhill knows what the resource database actually contains, even okiehsch isn't really familiar with the new ones, and I had to read the implementation to know how to use remove-attr.js.

For most people, that 2300+ lines of code are too much to chew, for this reason, I think we should add index and documentation for the resources in the wiki. I'm not too sure how should the wiki page be designed, but I can help once it is started.

[okiehsch]

I have to admit that even though I knew of remove-attr.js I did not think of trying to fix NanoAdblocker/NanoFilters#99 with such a filter.

A documentation of the reusable scriptlets should probably include simple example cases for each scriptlet, but I am not sure how detailed such a documention should be, i.e. how to explain it in a way that is understandable for the average user.

[jspenguin2017]

Yea, how to design the page can be a difficult question, I think it should include:

• The name (obviously)
• Accepted arguments
  • A short explanation for each
  • Whether it is optional, and its default value (if applicable)
• An explanation of what the resource does
  • Could include more detailed explanation for tricky arguments
• Common use case
• Examples

There should be one page for each type, arranged alphabetically (or some other reasonable non-random sorting logic), and a third page for difficult vocabulary such as DOM, attribute, event, etc.

A guide to the subset of RegExp that are often used in filters should help too.

[gwarser]

First screening. Something more to add? https://gist.github.com/gwarser/d1aabf7b013a7f3ae80dfcf6fb843abf

#Empty redirect resources
1x1-transparent.gif image/gif;base64
2x2-transparent.png image/png;base64
32x32-transparent.png image/png;base64
3x2-transparent.png image/png;base64
noopcss text/css
noopframe text/html
noopjs application/javascript
noopmp3-0.1s audio/mp3;base64
noopmp4-1s video/mp4;base64
nooptext text/plain

#General purpose scriptlets
abort-current-inline-script.js application/javascript
abort-on-property-read.js application/javascript
abort-on-property-write.js application/javascript
addEventListener-defuser.js application/javascript
addEventListener-logger.js application/javascript
disable-newtab-links.js application/javascript
nano-setInterval-booster.js application/javascript
nano-setTimeout-booster.js application/javascript
remove-attr.js application/javascript
set-constant.js application/javascript
setInterval-defuser.js application/javascript
setInterval-logger.js application/javascript
setTimeout-defuser.js application/javascript
setTimeout-logger.js application/javascript
sharedWorker-defuser.js application/javascript
window.open-defuser.js application/javascrip

[gwarser]

There should be one page for each type, arranged alphabetically (or some other reasonable non-random sorting logic), and a third page for difficult vocabulary such as DOM, attribute, event, etc.

I will prefer for start to add documentation comments in source code...

One paragraph of general description then list of resources with one line description and parameters should be enough.

A guide to the subset of RegExp that are often used in filters should help too.

No need to reinvent wheel, link to some "Regexp for dummies" will suffice.

I can help filling technical info, but someone will have to write descriptions (at least start of)

[jspenguin2017]

@gwarser Certainly we should link to more in depth RegExp resources, but tricks like this are probably not in there.

[gwarser]

This is programming experience and bit of hacking skills :)

[gwarser]

Notifications in gists does not work.

I try to chose list of site specific scriptlets and then create real wiki page.

[gwarser]

Why parseFloat and checks for NaN then abs if we allow only digits /^\d+$/?

	} else if ( /^\d+$/.test(cValue) ) {
		cValue = parseFloat(cValue);
		if ( isNaN(cValue) ) { return; }
		if ( Math.abs(cValue) > 0x7FFF ) { return; }

https://github.com/uBlockOrigin/uAssets/blob/2c68a4f5456e4677cec76f2784d2c1d7abc36efb/filters/resources.txt#L2118-L2121

This is true for any string, even empty one and false for any digit/number. Why this was coded this way?

	target = !(+target);

https://github.com/uBlockOrigin/uAssets/blob/2c68a4f5456e4677cec76f2784d2c1d7abc36efb/filters/resources.txt#L2004

[gorhill]

Why parseFloat and checks ...

Probably because I changed my mind to support only small integers but did not change the code to reflect this change of mind.

[gorhill]

false for any digit/number

This will be true with 0.

[jspenguin2017]

@gorhill What are you trying to achieve with that unary plus? That operator is really complicated, can we like, try to not use it?

[gwarser]

No need to complicate things, this is executed on scriptlet parameter, little chance to be something other than string.

[jspenguin2017]

Ah, right, I missed that part. Then why not use parseInt?

[gwarser]

Values set by set-constant.js can be changed if we set them to other type - is that by design? Only undefined looks really constant.

[jspenguin2017]

I think that is by design, as the code checks for that specifically.

[gwarser]

https://github.com/gorhill/uBlock/wiki/Resources-Library feel free to improve.