296836 - Convert nsIRDFService documentation to a doxygen-parseable format

Status: RESOLVED FIXED

(Core Graveyard :: RDF, defect)

Description

[Jeff Walden [:Waldo]]

The documentation's already there, but it's in a bad format ("//" instead of "/*
*/").  Converting it shouldn't be difficult, and it'll let places like XULPlanet
automatically generate documentation for the methods in it:

http://xulplanet.com/references/xpcomref/ifaces/nsIRDFService.html

Comment 1

[J.P.Klippel]

Attachment: adapted comments

Comment 2

[Axel Hecht]

Comment on attachment 188831 [details] [diff] [review]
adapted comments

This patch doesn't do any harm, and given that I will introduce a new API to
the rdf service, it's not a biggie, but should this fix return values and
@param stuff too?
And what about <tt> vs. <code>?

Comment 3

[Jeff Walden [:Waldo]]

Comment on attachment 188831 [details] [diff] [review]
adapted comments

While we're in here, we might as well fix typos and such in the method docs.

>+ * The RDF service interface. This is a singleton object, and should be
>+ * obtained from the <tt>nsServiceManager</tt>.

Change ", and" to " which", please.

>+     * Construct an RDF resource from a single-byte URI. <tt>nsIRDFSerivce</tt>

s/ivce/vice/

>+     * \note that the resource will <i>not</i> be ref-counted by the

>+     * \note that the nsIRDFService implementation may choose to

There are at least a few instances of @note as a delimiter in code (I don't
know whether it actually gets parsed or not, tho); perhaps it might be useful
here (and in the other places in the patch that use \note).

>+     * (accessable via nsIRDFResource::GetValue(const char* *aURI)) is

s/accessable/accessible/

Note also that I'm no doxygen wizard, and the only reason this is assigned to
me is that I planned to learn the markup and write the patch at some future
time.  Please request review from someone else.

Comment 4

[J.P.Klippel]

Attachment: revised patch

revised patch. 
Included all changes proposed by comment #3 (thanks). 

As for comment #2 I changed the <tt>-tags to be <code>-tags. I think the
code-tag is indeed a better markup for code than the more format-suggesting
tt-tag.

As for the parameter and return type documentation: I am not a big fan of
repeating what is already said in the source (the obvious e.g. this parameter
is a long value to create the literal from [nsIRDFInt GetIntLiteral(in long
aValue)]). 
I think the parameters are quite obvious and the return types, too. 
I propose as there are no real complicated parameters and return types to not
document the parameters and return types. But that sure is a philosophical
question.
As for the current patch I think it should (afaics) make it's way into the code
to fill in the holes in the generated documentation (see bug description).

Comment 5

[Axel Hecht]

Is there a plan to land this? I'd rather have this in than out, but I sure want
it out of the way.

Comment 6

[Mike Shaver (:shaver emeritus)]

Comment on attachment 188956 [details] [diff] [review]
revised patch

rs=shaver (bsmedberg should feel free to double-stamp these in the future!)

Comment 7

[:Gavin Sharp [email: [e-mail]]]

mozilla/rdf/base/idl/nsIRDFService.idl; new revision: 1.10; previous revision: 1.9