265112 - Add big scary warning to non-frozen interface files

Status: RESOLVED WONTFIX

(Core :: General, enhancement)

Description

[Darin Fisher]

We should add a big scary warning to any non-frozen interface file, saying
something like:

 /**
  * WARNING: THIS INTERFACE IS NOT FROZEN
  *
  * It may be modified or removed in future versions of Mozilla.  Whenever
  * this interface is modified, its UUID will be changed accordingly.
  */

I think we need this to draw attention to the fact that many interfaces exist
for internal use only.  We might want to add a link to the comment to point
developers at a page where they can find more info about frozen vs. non-frozen
Mozilla interfaces.

Comment 1

[Benjamin Smedberg]

Darin, I think that we need something more nuanced than this. There are at least
two kinds of "interfaces" involved here:

  1. interfaces that are entirely internal and will never be frozen
  2. interfaces that are heading towards frozenness in some future happy land

I think that the comment we add should be different for these types; we also
probably have interfaces where we haven't decided/don't know whether they should
be frozen.

Comment 2

[Darin Fisher]

bsmedberg, yeah... i agree.  but what promises can you really make about
"@status UNDER_REVIEW"?  you can't promise the vtable, or else it'd be frozen,
right?

Comment 3

[Benjamin Smedberg]

I was more thinking along these lines:

@status INTERNAL
        This interface is an internal Mozilla implementation detail. Embedders
        should NOT use this interface, because it will never be frozen. If you
        find yourself needing to use this interface, please send mail to
        _Module Owner <email@foo>_ to discuss the possibilities of freezing this
        functionality in some other manner.

Comment 4

[Darin Fisher]

saying "this interface will never be frozen" requires me to interpret each and
every interface.  i'd rather just state that the interface is frozen and state
along with that what frozen means in a short and consise way.  i'm open to using
different text for interfaces where we have indicated @status UNDER_REVIEW.

Comment 5

[Darin Fisher]

i'd rather just state that the interface is frozen [or not frozen] ...

Comment 6

[Darin Fisher]

sadly, i don't have time to implement this...