170662 - More comments in moz/defaults/pref/all.js (should go into profile/*.js too)

Status: RESOLVED INCOMPLETE

(Core :: Preferences: Backend, enhancement)

Description

[Andrei Boros]

Request comments for each setting in prefs.js, liprefs.js.

Look at the way smb.conf is for the samba package, or squid.conf is for the
squid proxy daemon, etc.

The configuration file is well commented, each setting well explained. 
Power users may want to play around with these settings files of Mozilla and
find themselves in need to dig a lot to find out the meaning of some settings,
or the range of values and possible effects for a setting.

Thus I request the following: 

Mozilla should have a fillable template for these 2 files in the installation
dir. These templates should contain all settings that can exist in them, all
commented, all with a placeholder where the value goes, all well commented about
their purpose, values, range, etc.
The prefs backend should, for each change in the prefs, to read this template,
uncomment each setting that should be other then the default, set the value in
the placeholder and save it in the profile dir.

In such a way, a power user can intimately configure Mozilla from files also.

Comment 1

[Andrei Boros]

Attachment: Sample smb.conf file to exemplify how I meant the request.

Comment 2

[Boris Zbarsky [:bzbarsky]]

That's what all.js is supposed to be for, mostly.  Yes, the commenting in that
could be expanded...

Comment 3

[Daniel Wang]

[mozilla install directory]/defaults/pref/all.js

reporter, how about "more comments in moz/defaults/pref/all.js"
as summary?

Comment 4

[Andrei Boros]

Agree.
But don't forget that they should go to the profile *.js files too.

In my current installation (1.2a) I see some comments in all.js, but not in the 
prefs.js and liprefs.js in the profile folder.

Comment 5

[Brian Nesse (gone)]

Mozilla does not use liprefs.js. That must be a remnant from a 4.x profile... 

prefs.js is a generated file... it is created from a hash table in memory...
there is now way to tie comments to the data.

Commenting the prefs in all.js will require either someone who knows all of the
prefs in mozilla ([e-mail]) or buy-in from all of the module owners
(at a minimum). Given the collection of bugs (internal and external) pertaining
to the documenting of these prefs, I don't think this is very likely either.

Comment 6

[Andrei Boros]

But isn't it possibly to take the comments from all.js too when taking 
configuratoin items?

Comment 7

[Andrei Boros]

Sorry, I forgot to add: take the _existing_ comments from all.js when writing 
the prefs.js. 
Then all new comments added along the way will always be there in prefs.js when 
needed.

Comment 8

[Christian :Biesinger (don't email me, ping me on IRC)]

that would be very difficult

also, it would increase startup time I think.

and, _why_?

Comment 9

[Boris Zbarsky [:bzbarsky]]

Comments are stripped out in the tokenizer; that's what tokenizers are for.  So
no, it's not possible without major work.

I agree that there's no reason to do it if we just

1)  Make all.js up-to-date
2)  _publicise_ all.js

Comment 10

[Andrei Boros]

can't the tokenizer just copy comment lines as is? consider it a token that does
not change.

Comment 11

[Christian :Biesinger (don't email me, ping me on IRC)]

well, AIUI preferences work like this: On startup, the js file
all.js/prefs.js/user.js etc. are _executed_. during this, of course, the
comments are stripped. while executed, the prefs are stored in memory in some
kind of data structure.

later on, on shutdown, the in-memory datastructure is written to disk.

so there is no direct relation between reading the prefs and writing them.

Comment 12

[Vaclav Dvorak]

See bug 158384. Having both would be redundant, and there is already some
progress on the other one, so I propose WONTFIXing this (or DUPing it to 158384).

Comment 13

[Boris Zbarsky [:bzbarsky]]

I'll believe it when I see it.  Marking dep; if that ever gets fixed, this can
probably be resolved.

Comment 14

[Nickolay_Ponomarev]

Wrong dependency. bug 158384 is about generic prefs docs (what are prefs, where
they are stored etc). The bug to explain what prefs do what is bug 178685.
There's http://preferential.mozdev.org btw

Myself, I don't think the comments should be in all.js (is it read on startup?),
a link to online documentation is be enough.