From 4711e14abcc082ffa8136b372948f3141a64d6fb Mon Sep 17 00:00:00 2001
From: "waterson%netscape.com" <waterson%netscape.com>
Date: Tue, 2 Mar 1999 00:59:03 +0000
Subject: [PATCH] Updated documentation on ReigsterDataSource() &&
 RegisterResource().

---
 rdf/base/public/nsIRDFService.h | 35 ++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/rdf/base/public/nsIRDFService.h b/rdf/base/public/nsIRDFService.h
index bfe2c3845077..0b8910d609c9 100644
--- a/rdf/base/public/nsIRDFService.h
+++ b/rdf/base/public/nsIRDFService.h
@@ -74,7 +74,28 @@ public:
     NS_IMETHOD GetLiteral(const PRUnichar* value, nsIRDFLiteral** literal) = 0;
 
     /**
-     * Registers a resource with the RDF system, making it unique w.r.t. GetResource.
+     * Registers a resource with the RDF system, making it unique w.r.t.
+     * GetResource.
+     *
+     * An implementation of nsIRDFResource should call this in its
+     * Init() method if it wishes the resource to be globally unique
+     * (which is usually the case).
+     *
+     * NOTE that the resource will <i>not</i> be ref-counted by the
+     * RDF service: the assumption is that the resource implementation
+     * will call nsIRDFService::UnregisterResource() when the last
+     * reference to the resource is released.
+     *
+     * NOTE that the nsIRDFService implementation may choose to
+     * maintain a reference to the resource's URI; therefore, the
+     * resource implementation should ensure that the resource's URI
+     * (accessable via nsIRDFResource::GetValue(const char* *aURI)) is
+     * valid before calling RegisterResource(). Furthermore, the
+     * resource implementation should ensure that this pointer
+     * <i>remains</i> valid for the lifetime of the resource. (The
+     * implementation of the resource cache in nsIRDFService uses the
+     * URI maintained "internally" in the resource as a key into the
+     * cache rather than copying the resource URI itself.)
      */
     NS_IMETHOD RegisterResource(nsIRDFResource* aResource, PRBool replace = PR_FALSE) = 0;
 
@@ -97,14 +118,14 @@ public:
 
     /**
      * Register a <i>named data source</i>. The RDF service will call
-     * <tt>nsIRDFDataSource::GetURI()</tt> to determine the URI under which to 
-     * register the data source.
+     * <tt>nsIRDFDataSource::GetURI()</tt> to determine the URI under
+     * which to register the data source.
      *
      * Note that the data source will <i>not</i> be refcounted by the
-     * RDF service! The assumption is that an RDF data source registers
-     * with the service once it is initialized (via <tt>nsIRDFDataSource::Init()</tt>),
-     * and unregisters when the last reference to the data source is
-     * released.
+     * RDF service! The assumption is that an RDF data source
+     * registers with the service once it is initialized (via
+     * <tt>nsIRDFDataSource::Init()</tt>), and unregisters when the
+     * last reference to the data source is released.
      */
     NS_IMETHOD RegisterDataSource(nsIRDFDataSource* dataSource,
                                   PRBool replace = PR_FALSE) = 0;