823023 - Reduce comments in prefs.js to "Do not edit this file."

Status: RESOLVED FIXED

(Core :: Preferences: Backend, defect, P5)

Description

[S. Kerman]

User Agent: Mozilla/5.0 (Windows NT 5.1; rv:17.0) Gecko/20100101 Firefox/17.0
Build ID: 20121128204232

Steps to reproduce:

Inspecting the Thunderbird prefs.js file, one finds the following statements: 
"To make a manual change to preferences, you can visit the URL about:config
For more information, see http://www.mozilla.org/unix/customizing.html#prefs"


Actual results:

I don't understand how it's possible to visit the URL stated above using Thunderbird.  As far as I can see, that URL can only be visited with Firefox, which will open the prefs for Firefox, not for Thunderbird.

I don't see anything enlightening on this topic at http://www.mozilla.org/unix/customizing.html#prefs


Expected results:

Thunderibird messed up my SMTP server entries, changing their order in the menu listing.  I have a reason to want to have them in a specific order.  I'm not interested in deleting and re-entering them to restore their original order.  I see the series of entries listed in prefs.js as "user_pref ("mail.smtpserver.smtp#.description", ["server name"]); and after the last one a list:
user_pref("mail.smtpservers", "smtp5,smtp1,smtp3,smtp8,smtp4,smtp2,smtp6,smtp7,smtp9");
which determines the order in which they appear in the menu.

Yes, I can shut Thunderbird down and manually edit prefs.js but it seems to me that if the instructions at the top of this file are incorrect about opening about:config they need to be changed and if correct they need to explain how this file can be opened for Thunderbird rather than Firefox.

Comment 1

[Chris Ilias [:cilias]]

If I understand correctly, you think the line "To make a manual change to preferences, you can visit the URL about:config" should be changed because it doesn't apply to Thunderbird users.

So there are a few issues here:
* As far as I know, that line is part of the core code shared by Firefox, Thunderbird, and other Mozilla-based applications.
* about:config is also shared code, but there just isn't a place in TB to type the URL. For that reason, TB designers added a button in the Options window (under Advanced > General) called [Config Editor] that will open about:config in TB.
* Because of the existence of about:config, editing prefs.js is not recommended at all.

My proposal:
Rather than adding instructions for more Mozilla applications, I would rather just remove the entire comment, with the exception of "Do not edit this file."


Sidenotes:
* about:config is not a website. It's part of the application.
* The line about www.mozilla.org was removed in Mozilla13 (bug 701322). Your prefs.js was probably created before then.

Comment 2

[Wayne Mery (:wsmwk)]

Given the reporter's last paragraph I'd say there is no objection to comment 1

Comment 3

[Nicholas Nethercote [inactive]]

Attachment: Bug 823023 - Tweak the comment at the top of prefs.js.

Specifically:
- Make the warning about editing in all-caps;
- Make it clear that about:config is a browser thing;
- Add a mention of the user.js file;
- Use C++ comments, because I prefer them to C comments and I am the module
  owner :)

Review commit: https://reviewboard.mozilla.org/r/217404/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/217404/

Comment 4

[Mike Hommey [:glandium]]

Comment on attachment 8947682 [details]
Bug 823023 - Tweak the comment at the top of prefs.js.

https://reviewboard.mozilla.org/r/217404/#review223150

::: modules/libpref/Preferences.cpp:2362
(Diff revision 1)
> -  " *"
> +  "//"
>    NS_LINEBREAK
> -  " * To make a manual change to preferences, you can visit the URL "
> +  "// To change a preference value, you can either: "
> -  "about:config"
>    NS_LINEBREAK
> -  " */"
> +  "// - Modify it via the UI (in the browser, this is via about:config); or"

about:config is kind of a last resort. The conventional way to change prefs is through the "normal" UI, such as about:preferences.

Comment 5

[Nicholas Nethercote [inactive]]

> > +  "// - Modify it via the UI (in the browser, this is via about:config); or"
> 
> about:config is kind of a last resort. The conventional way to change prefs
> is through the "normal" UI, such as about:preferences.

For the small fraction of prefs that can be changed through "normal" UI, sure. But if somebody is inspecting prefs.js, they're probably way beyond that point...

I'll change it to "Modify it via the UI (e.g. via about:config in the browser)". That makes it sound less like about:config is the only way to change it.

Comment 6

[Nicholas Nethercote [inactive]]

https://hg.mozilla.org/integration/mozilla-inbound/rev/841512e696b91825d24c6dd1a18d277c5f7d2be4
Bug 823023 - Tweak the comment at the top of prefs.js. r=glandium

Comment 7

[Arthur Iakab [arthur_iakab]]

https://hg.mozilla.org/mozilla-central/rev/841512e696b9