search

thunderbird / developer-docs

Developer documentation for Thunderbird contributors.
https://developer.thunderbird.net
82 stars 77 forks source link

Mention ExtensionCommon.jsm in experiments guide #83

Closed rsjtdrjgfuzkfg closed 4 years ago

rsjtdrjgfuzkfg commented 4 years ago

It is likely helpful to mention a few helper methods; most notably, ExtensionCommon as a whole does not get auto-generated documentation but contains goodies like NoCloneSpreadArgs. I also tried to clarify the situation for returning privileged objects directly from API methods (which is actually possible for non-async methods, which I did not consider earlier).

jobisoft commented 4 years ago

In the new hint where you mention the additional descriptions and information in ExtensionCommon.jsm, could you provide links to the lines with important things you had in mind? That file is huge and I assume it is very difficult for others to find the important stuff. Even if it becomes a longer bullet list of links, having a summary due to the link titles directly in the document will help a great deal. And saves readers a ton of time.

rsjtdrjgfuzkfg commented 4 years ago

@jobisoft I considered that, but decided against that due to two issues: one, it is not yet possible to permalink mozilla-esr78, as the branch is not yet renamed/created (unless I missed something?). So I linked mozilla-central, but I don't expect line numbers to be sufficiently stable there. Two, is is not possible to easily determinate which parts may be relevant. I know the parts I needed, but I'd assume that every experiment has different needs.

That's why I settled with writing 'documentation blocks', as grepping for /** is a good way to get an overview on what's available (and if you know what you search for, you can directly grep for the thing you need).

If it is of any use to you: the main reason why I added it is because of NoCloneSpreadArgs (currently line 216+) and the fact that it contains the members of an EventManager's fire object (currently line 2401+). Both topics that are not currently listed in the official docs, but were useful to me.

From the related modules in the same folder, the most relevant is probably ExtensionParent.jsm's GlobalManager, which provides the methods to get the experiment in a parent fashion (used in the snippet to load a JSM that is currently in the guide).

If this did not convince you, I can take the note out – or you can modify it if you know a better way?

jobisoft commented 4 years ago

I follow your second point, which rules out my suggestion. Even if the branch is not yet frozen, can we link to some of the most important files? To be honest, I have not yet looked at the source files here so I do not know, which one would be interesting. Anything besides

What I have seen: You can link against a certain revision, which could be a workaround until mozilla-esr78 is done: https://hg.mozilla.org/mozilla-central/file/0542461e3da7318b777e2e606dbbfff69c298924/toolkit/components/extensions

I will merge this in a couple of seconds, to get the changes published. But your feedback on the above would still be valuable.

Did you get my private matrix message about gitbook?

rsjtdrjgfuzkfg commented 4 years ago

I think ExtensionCommon is the most important file, followed by ExtensionParent. It is likely that ExtencionChild will become important once Thunderbird goes multi-process, but it seems less important right now as we can still use ExtensionParent from child implementations.

ExtensionUtils contains tons of helpers that could be useful in a wide range of situations (notably ExtensionError, which permits nicer error messages to become available in the WebExtension scope – but I have to admit that I live with the browser console and 'unknown' errors in the WebExtension scopes for now).

It is likely that other files are very useful for more specific problems and that I missed something.

I did not want to link to a revision, as I'd fear to forget to update it later. If you are good at remembering things that is a good option, though.

Regarding matrix, I'm using that from a browser, so I did not see your attempt to communicate until now. And as of now I only see a message that the decryption failed – maybe because I don't have any persistence in my browser or because I logged out in between sessions (I thought the keys are stored on mozilla servers to do the monitoring they describe in their ToS and I get them back while logging in with the recovery password).

In general, email is a more stable way to reach me (PGP 0x2442CA99C74274B623F20394D185157C376F3F9E) ;)