XPCOM Documentation tree
Alec Flett
to actually write some, starting with XPCOM... and I need your help.
There's an outline with links here:
http://www.mozilla.org/projects/xpcom/doc/
The idea is that this guide is for clients of XPCOM - these are not the
internal details of how this stuff works, but rather a set of "how to
use XXX" style documents. The string guide and array guides are good
examples. If you're getting this e-mail then I'm asking you to help out
(see below) - at least getting us started.
I've tried to make this the comprehensive list of "what is in xpcom.dll"
without covering too much obsolete stuff like nsFileSpec. I went through
a list of every file in mozilla/xpcom (except the XPConnect stuff) and
tried to figure out where that file would be documented.. and came up
with the above list.
to get this kicked off, I've added some skeleton docs for what I believe
to be the "hotspots" of documentation in XPCOM - the areas that are:
- well defined and thus easily documented
- well owned, and thus has a good expert
- the areas that people use the most and thus need the documentation
desperately.
I've linked to these skeleton docs in the link above.
There are a few areas that I think we can start documenting now, and
here's where I need your help:
- directory service (ccarlen)
- timers (pavlov)
- string escaping (darin)
- pipes (darin)
- streams (darin)
- proxies, threads (dougt)
- event queues (danm) (overlap with proxies/threads, obviously)
- nsIFile and friends (dougt)
- fastload (brendan)
- atoms (alecf)
- property lists (alecf)
- hashtables (alecf, bsmedberg, jkeiser)
- observers (alecf, dougt)
There are lots of other issues that we can dwell on like:
- these docs are in the wrong place on mozilla.org
- I don't like the style/organization/formatting
- this stuff isn't frozen
- I want to write my docs in TeX
all I ask is that *for now*, you table these issues. We can always move
the docs, reformat them, freeze/obsolete interfaces, etc later.. but for
now if you have the time, it would be great if you could just start
filling in the docs themselves - the content is what is important here.
If we get a more comprehensive mozilla.org doc story, we can always move
the stuff you write into that system.
Also, I'm not married to this particular organization, it is just what
made sense to me at the time. If you want to move/combine/split some of
these subject areas, feel free - lets not discuss it too much lets just
do it!
Alec
P.S. see http://www.mozilla.org/README-cvs.html for easy instructions to
check out the files, or just:
cvs -d:pserver:email%add...@gila.mozilla.org:/cvsroot co
html/projects/xpcom/
Daniel Wang
> I got tired of all the meta-discussion about documentation
that's probably because newsgroup is a good place for such discussion
and Bugzilla is a better place for discussing specifics of a doc?
> and decided
> to actually write some, starting with XPCOM... and I need your help.
> There's an outline with links here:
>
> http://www.mozilla.org/projects/xpcom/doc/
why not http://www.mozilla.org/catalog/architecture/xpcom/ ?
documentation and project-specific information should be kept separate
And please open a bug for tracking this
> The idea is that this guide is for clients of XPCOM - these are not the
> internal details of how this stuff works, but rather a set of "how to
> use XXX" style documents. The string guide and array guides are good
> examples. If you're getting this e-mail then I'm asking you to help out
> (see below) - at least getting us started.
>
> [snip]
>
> I've linked to these skeleton docs in the link above.
> There are a few areas that I think we can start documenting now, and
> here's where I need your help:
> - [snip]
> - nsIPref* (daniel?)
>
> There are lots of other issues that we can dwell on like:
> - these docs are in the wrong place on mozilla.org
> - I don't like the style/organization/formatting
fantasai is working on a new style guide
> [snip]
> - I want to write my docs in TeX
Please use HTML or plain/text:
- most documentation effort are done in HTML/text
- after you check in something, you should make sure the content
isn't reformatted so much content diff doesn't show up in CVS .diff
> [snip]
>
> Also, I'm not married to this particular organization, it is just what
> made sense to me at the time. If you want to move/combine/split some of
> these subject areas, feel free - lets not discuss it too much lets just
> do it!
> Alec
>
> P.S. see http://www.mozilla.org/README-cvs.html for easy instructions to
> check out the files, or just:
README-cvs.html is obsolete. Use
http://www.mozilla.org/catalog/development/website/cvs-website.html
and somebody please link
http://www.mozilla.org/catalog/development/tools/cvs-intro.html from
http://www.mozilla.org/cvs.html
> cvs -d:pserver:email%add...@gila.mozilla.org:/cvsroot co
> html/projects/xpcom/
<style type="text/css">
a[href*="http://lxr"] { color: #6633cc; /* text-decoration:
underline; */}
th, td { vertical-align:top; }
.indent { margin-left: 5em; }
.table { border-collapse: collapse; }
.table td, .table th {
border: 1px solid #cccccc;
padding: 0.2em;
padding-left:0.3em;
padding-right:0.3em;}
.table th { text-align:left; }
pre.codeExample {
margin-left:4em;
margin-right:4em;
border:1px solid #cccccc;
background-color:#f6f6f6;
padding:1em;
}
.note { border-top:1px solid #cccccc; border-bottom:1px solid
#cccccc;width:40em; }
</style>
<script type="text/javascript">
function load() {
cvsSrc = new Array (
{re:/nsReadConfig\.(cpp|h)/, lxr:"extensions/pref/autoconfig/src/"},
{re:/prefapi\.cpp/, lxr:"modules/libpref/src/"},
{re:/nsPrefService\.cpp/, lxr:"modules/libpref/src/"},
{re:/pldhash\.h/, lxr:"xpcom/ds/"}
)
for (var i=0; i< document.links.length; i++) {
href = document.links[i].href;
if (href.indexOf('cvs:')==0) {
for (var j=0; j < cvsSrc.length; j++) {
if (href.match(cvsSrc[j].re)) {
href = href.replace(cvsSrc[j].re,
cvsSrc[j].lxr + "$&");
break;
} // if
} // for
document.links[i].href =
href.replace(/^cvs:/,
"http://lxr.mozilla.org/mozilla/source/");
} // if
}//for
}
</script>
<body onload="load();">
<p>This reference is intended for Mozilla developers and Mozilla
application developers. Users and system administrators looking
for information on editing preferences and changing defaults should
read <a href="/catalog/end-user/customizing/briefprefs.html">A Brief
Guide to Mozilla+Netscape Preferences</a>.</p>
<h3>Preference XPCOM Interfaces</h3>
<p>The libPref module provide back-end preferences access
facilities. It has two interfaces—nsIPrefService and
nsIPrefBranch<sup>†</sup>—. Built on top of
libPref are two extensions: AutoConfig and SystemPref.
AutoConfig provides system administrators facilities for
preference locking. SystemPref is for ????.</p>
<p class="note"><sup>†</sup>nsIPref has been deprecated.</p>
<h4>Interfaces</h4>
<p>The <strong><tt>nsIPrefService</tt></strong> interface is the main
entry point into the back-end preferences management library. The
preference service is directly responsible for the management of the
preferences files and also facilitates access to the preference branch
object which allows the direct manipulation of the preferences
themselves.</p>
<p>The following is an example code to read and set preferences in
JavaScript:</p>
<pre class="codeExample">
<!--
var pref;
try {
pref = ( Components.classes["@mozilla.org/preferences;1"]
).getService(Components.interfaces.nsIPrefService);
} catch (error) {
// fails to load pref service
}
// getting preferences
try {
prefValue = pref.GetCharPref("prefName");
// prefValue = pref.GetBoolPref("prefName");
// prefValue = pref.GetIntPref("prefName");
} catch (error) {
// preference loading failed, or
// preference hasn't been set
prefValue = defalutValue;
}
// setting preferences
pref.SetCharPref("prefName", "prefValue");
// pref.SetBoolPref("prefName", prefValue);
// pref.SetIntPref("prefName", prefValue);
-->
</pre>
<p class="note">
<b>Note</b> preference names are case-sensitive.</p>
<p>nsIPrefService does not have any function for resetting a preference
to its default. Developers may work around this issue by taking
advantage of preferences <a href="#compression">compression</a>; to
reset a preference, first set the default value (e.g. using
<code>SetDefaultBoolPref()</code>), then set the preference with the
same value.</p>
<h3>Preference Navigation</h3>
<p>Instead of always specifying full preference names, you can query
preferences from a parent node using the nsIPrefBranch interface and
read/set a preference by querying the node name.
</p>
<pre class="codeExample">
nsCOMPtr<nsIPrefBranch> prefBranch;
nsCOMPtr<nsIPrefService> prefService =
do_GetService(NS_PREFSERVICE_CONTRACTID, &rv);
if (NS_FAILED(rv)) return rv;
if (prefService) {
prefService->;GetBranch("browser.",
getter_AddRefs(prefBranch));
}
// read "browser.fixup.alternate.enabled" pref
prefBranch->GetBoolPref("fixup.alternate.enabled",
getter_Copies(strValue));
</pre>
<h3>Reading a Preference of Arbitrary Type</h3>
<p>The <code>GetPrefType(char*)</code> method returns a flag indicating
<a href="cvs:prefapi.h#188">type</a>. You can use this method to
determine if a preference is a Boolean, integer, or string. The
following is a C++ example of using
<code>nsIPrefBranch::GetPrefType()</code> to read a preference of
arbitrary type:</p>
<pre class="codeExample">
#include "nsIPrefBranch.h"
#include "nsIPrefService.h"
#include "nsIServiceManager.h"
:
:
nsresult test::readPref(const char *aPrefName)
{
nsresult rv;
nsCOMPtr<nsIPrefService> prefService =
do_GetService(NS_PREFSERVICE_CONTRACTID, &rv);
if (NS_FAILED(rv))
return rv;
nsCOMPtr<nsIPrefBranch> prefBranch;
rv = prefService->GetDefaultBranch(nsnull, getter_AddRefs(prefBranch));
if (NS_FAILED(rv))
return rv;
char* strValue = nsnull;
PRInt32 intValue = 0;
PRBool boolValue = PR_FALSE;
PRInt32 prefType = nsIPrefBranch::PREF_INVALID;
rv = prefBranch->GetPrefType(aPrefName, &prefType);
switch(prefType) {
case nsIPrefBranch::PREF_STRING:
prefBranch->GetCharPref(aPrefName, getter_Copies(strValue));
// do other stuff here
break;
case nsIPrefBranch::PREF_INT:
prefBranch->GetIntPref(aPrefName, &intValue);
// do other stuff here
break;
case nsIPrefBranch::PREF_BOOL:
prefBranch->GetBoolPref(aPrefName, &boolValue);
// do other stuff here
break;
default:
return NS_ERROR_FAILURE;
}
return NS_OK;
}
</pre>
<h3>Listening for Preference Changes</h3>
<p>You can register an observer with a Preference object to listen to any
change to a particular preference you are interested in. The following is
a C++ example of listening to the <tt>browser.fixup.alternate.enabled</tt>
preference.</p>
<pre class="codeExample">
nsresult tester::Init()
{
nsresult rv;
if (!gPrefBranch) {
nsCOMPtr<nsIPrefService> prefs =
do_GetService(NS_PREFSERVICE_CONTRACTID, &rv);
NS_ENSURE_SUCCESS(rv, rv);
rv = prefs->GetBranch(PREF_BRANCH_BASE, &gPrefBranch);
NS_ENSURE_SUCCESS(rv, rv);
}
nsCOMPtr<nsIPrefBranch> pb = do_QueryInterface(gPrefBranch);
if (pb) {
pb->AddObserver("browser.fixup.alternate.enabled", this, PR_FALSE);
}
}
// inherited from public class nsIObserver
NS_IMETHODIMP tester::Observe(nsISupports *aSubject,
const char *aTopic,
const PRUnichar *aSomeData)
{
if (!nsCRT::strcmp(aTopic, "nsPref:changed")) {
NS_ENSURE_STATE(gPrefBranch);
PRBool boolValue = PR_FALSE;
if (!nsCRT::strcmp(aSomeData, "browser.fixup.alternate.enabled") {
// domain autocompletion is has been enabled/disabled
gPrefBranch->GetBoolPref("browser.fixup.alternate.enabled",
&boolValue);
// do something else
}
}
}
</pre>
<h3>Locking and Unlocking a Preference</h3>
<p>The following is a C++ code example of locking and unloading a preference
dynamically:</p>
<pre class="codeExample">
RBool isLocked;
prefBranch->PrefIsLocked("preferencename", &isLocked);
if (isLocked)
prefBranch->UnlockPref("preferencename");
:
prefBranch->LockPref("preferencename");
</pre>
<p style="color:red">Example of loading a custom user pref file via
nsIPrefService::ReadUserPrefs needed.</p>
Christian Biesinger
> README-cvs.html is obsolete. Use
> http://www.mozilla.org/catalog/development/website/cvs-website.html
README-cvs.html is much newer than that other page.
Axel Hecht
Like, what do documentation folks do these days? There has been lots of
discussion about which pages to link and whatnot over in .seamonkey, and
those actually getting stuff done got it done, without any of these
notes whatsoever. Comments like just this are exactly what alec is
getting tired off. At least that's my guess. And my personal experience,
too.
As alecf pointed out, he's actually talking about content for a change,
and not what's going where and which color it should be in.
And don't get me started on that dead useless child called catalog.
Axel
Alec Flett
> Alec Flett wrote:
>
>> I got tired of all the meta-discussion about documentation
>
>
> that's probably because newsgroup is a good place for such discussion
> and Bugzilla is a better place for discussing specifics of a doc?
>
Not its because we have the classic "too many chiefs" problem - everyone
wants to declare that docs should be written this way or that way or
should live here or there and nobody wants to actually write docs.
I am absolutely flabergasted that the response to actual documentation
has been "please don't check this in without following some idioic guide
that hasn't been written yet"
>
> why not http://www.mozilla.org/catalog/architecture/xpcom/ ?
because I'm actually writing the docs. When you write them, you can put
them there.
> documentation and project-specific information should be kept separate
Whatever.
>
> And please open a bug for tracking this
No. I'm writing docs not filing bugs. File them yourself.
>> here's where I need your help:
>> - [snip]
>> - nsIPref* (daniel?)
HElloo... nsIPref is not part of XPCOM.
>
>
> fantasai is working on a new style guide
wake me when its over. Kudos for Fantasai for actually writing it though.
>
>> [snip]
>> - I want to write my docs in TeX
>
>
> Please use HTML or plain/text:
Oh god... lighten up. That was a joke.
>
> README-cvs.html is obsolete. Use
> http://www.mozilla.org/catalog/development/website/cvs-website.html
So the doc with correct instructions is obsolete and the doc with all
the typos that makes no sense is the one we should use? Good luck with that.
> I think you are missing the motives behind all the meta-d11n efforts. It's very difficult to become a contributor in documentation (or QA, or Mozilla development). A lot of people have announced their intent to help, but guess what? Most got no assistance from any human being or meta-document. Is there any wonder why nobody is writing documentation and people are trying to fix this?
The fact is a lot of people have offered meta-help - help organizing
documents, help telling other people how to write their documents, but
very, VERY few people have actually sat down and written anything. The
problem is not some meta document or someone holding someone else's
hand. The problem is nobody is writing docs. A style guide or a
documentation plan is not going to solve that.
Look, I'm sick of all this process with respect to documentation. You
guys need to just get over yourselves and pitch in with actual work. I
see twenty people working in a bubble trying to direct people who
actually produce things, to produce them by THEIR rules which don't even
exist. When I see you've demonstrated some reasonable expertise in this
area, I'll listen, but until then either get your hands dirty or quiet down.
I'm going to write a "how to write documentation" doc this week. It will
be a sort of mozilla-specific "how to be a tech writer"
Alec