2004061 - Add documentation around the locked property in Setting and Preferences code

Status: NEW

(Firefox :: Settings UI, task)

Description

[Mark Kennedy [:mark]]

The locked property appears throughout the Setting and Preference code. But it's not clear what this property is. What does it mean when a setting or pref is in a "locked" state? How do you use it? Where does the value come from? How can you set it? etc.

So we should add some JSDoc around the locked property to help engineers who are using it for the first time or just need a refresher when working with this property in code.

Note: Doing this via JSDoc would allow engineers to quickly see it at a glance via Intellisense (when hovering over the property in the codebase in their IDE), which can be more helpful than throwing this in a Google doc or some other place where it may be more difficult to find.

Comment 1

[Mark Kennedy [:mark]]

We can add the documentation above the locked property for both Setting and Preference classes.

Looks like the closest thing we already have documented is in this modules/libpref/nsIPrefBranch.idl file, which we can use as a base or maybe JSDoc-inherit from. Although mstriemer says that there has been some confusion around whether or not it's totally accurate.

mstriemer on slack:

always return the default value regardless of whether there is a user set value or not.

I thought this was the case but I'm pretty sure there's still a way to have it with a non-default value. It might be that the user value is ignored, and the main pref branch value is returned. tbh I'm not 100% sure how the default value stuff works :sweat_smile: I was looking at checking default values before with someone and we were very confused about what it was saying was default or not

Comment 2

[Mark Striemer [:mstriemer]]

For prefBranch.lockPref("foo") I see this for my LSP hover hint:

(method) nsIPrefBranch.lockPref(aPrefName: string): void

Using go-to-definition it takes me to https://searchfox.org/firefox-main/rev/6ef3d44ec645cc393300806684d11c6de0b302b0/tools/%40types/generated/lib.gecko.xpcom.d.ts#10164

Having the docs from the IDL included in our .d.ts files could be helpful when looking at the the linked Setting/Preference files, and would likely allow us to @inheritdoc if application or at least @link to the underlying API

Manually copying the IDL docs in I get this which is much nicer:

(method) nsIPrefBranch.lockPref(aPrefName: string): void

Called to lock a specific preference. Locking a preference will cause the
preference service to always return the default value regardless of
whether there is a user set value or not.

*@param* `aPrefName` — The preference to be locked.  

*@note*  
This method can be called on either a default or user branch but, in
effect, always operates on the default branch.  

*@throws* — Error The preference does not exist or an error occurred.  

*@see* — unlockPref