How to mark an interface as frozen

[Chak Nanga]

Here's a general outline of how an idl file of a FROZEN interface should look like - specifically
what sections we'd like to have and their order:

1. The Copyright section
2. #include's of any other required idl files
3. Forward declarations of other interfaces refered to in the methods of the current interface
4. A general description of the current interface's purpose/functionality(with the FROZEN keyword)
5. Desciptions of each of the methods in the interface.

When writing descriptions for sections 4 and 5 above please follow the JavaDoc comment guidelines at http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Here's a sample template which follows the guidelines set above:

/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
*
* The contents of this file are subject to the Netscape Public
* License Version 1.1 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of
* the License at http://www.mozilla.org/NPL/
*
* Software distributed under the License is distributed on an "AS
* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
* implied. See the License for the specific language governing
* rights and limitations under the License.
*
* The Original Code is mozilla.org code.
*
* The Initial Developer of the Original Code is Netscape
* Communications Corporation.  Portions created by Netscape are
* Copyright (C) 2001 Netscape Communications Corporation. All
* Rights Reserved.
* * Contributor(s): *        Adam Lock <[EMAIL PROTECTED]>
*/

#include "nsISupports.idl"

interface nsIDOMNode;

/**
* An optional interface for embedding clients wishing to receive
* notifications for when a tooltip should be displayed or removed.
* The embedder implements this interface on the web browser chrome
* object associated with the window that notifications are required
* for.
*
* @status FROZEN
*/
[uuid(44b78386-1dd2-11b2-9ad2-e4eee2ca1916)]
interface nsITooltipListener : nsISupports
{
   /**
    * Called when a tooltip should be displayed.
    *
    * @param aXCoords The tooltip left edge X coordinate.
    * @param aYCoords The tooltip top edge Y coordinate.
    * @param aTipText The text to display in the tooltip, typically obtained
    *        from the TITLE attribute of the node (or containing parent)
    *        over which the pointer has been positioned.
    *
    * @note
    * Coordinates are specified in pixels, relative to the top-left
    * corner of the browser area.
    *
    * @return NS_OK Tooltip was displayed.
    * @return Other No tooltip was displayed.
    */
   void onShowTooltip(in long aXCoords, in long aYCoords, in wstring aTipText);
 
   /**
    * Called when the tooltip should be hidden, either because the pointer
    * has moved or the tooltip is to be hidden.
    */
   void onHideTooltip();
};