Mike Shaver wrote:
> Doug Turner wrote:
>
> Need to explicitly list result codes and out-parameter states.
>
> > * Make sure that contract-ids and classIDs are defined consistantly.
> > Do we even want to expose ClassIDs?
>
> Neither contract IDs nor class IDs should appear in interface
> definition files, IMO. They're representations of specific
> implementations of one or more interfaces, and we should probably just
> document them somewhere external to the IDL files. (We had a
> discussion in this group some months ago, started by alecf IIRC, and I
> think the consensus was that contract IDs should be well-known strings
> and not necessarily included in any header files. I can't find the
> thread right now, though, so I might be misremembering.)
>
> I'm also not really keen on us documenting our frozen services and
> components via C++ header files. Can't we just write language-neutral
> HTML for this?
In general the definition file associated with an XPCOM component will
contain more than just documentation. I am proposing that each of these
files contain the following:
1. definition of the Class-Id (or Class-Ids for versioned components)
2. #includes for each interface whoch the component supports.
3. documentation describing the component
4. any other component-specific definitions which may be appropriate.
Please refer to nsCWebBrowser.idl as a reference...
I do *not* believe that IDL files are the appropriate place for this
type of information :-) However, I am reluctant to restrict ourselves
to only supplying HTML documentation along with components... That's why
I think that header files provide an adaquate compromise...
-- rick
