upstream/oracle/vpanels: comparison usr/src/doc/rad-dev/c-adr-idl.xml

equal deleted inserted replaced

-:2e056f355d24
+:025928ac8888
 </para>
 <section><title>Overview</title>
 <para>
 The top level element in an <acronym>ADR</acronym> definition
-document is an <sgmltag class='element'>interface</sgmltag>.  The
+document is an
-<sgmltag class='element'>interface</sgmltag> element has one
+<sgmltag class='element'>api</sgmltag>.  The
+<sgmltag class='element'>api</sgmltag> element
+has one
 attribute, <sgmltag class='attribute'>name</sgmltag>, which is used
 to name the output files.  The element contains one or more derived
-type or <acronym>API</acronym> definitions.  As there is no
+type or interface definitions.  As there is no
-requirement that an <acronym>API</acronym> use derived types, there
+requirement that an interface use derived types, there
 is no requirement that any derived types be specified in an
-interface document.  To let consumers use the data typing defined
+<acronym>API</acronym> document.
-by <acronym>ADR</acronym> for non-<acronym>API</acronym> purposes,
+To let consumers use the data typing defined
-there is no requirement that an <acronym>API</acronym> is defined
+by <acronym>ADR</acronym> for non-interface purposes,
+there is no requirement that an interface is defined
 either.  (At least one thing, derived type or
-<acronym>API</acronym>, <emphasis>must</emphasis> be defined,
+interface, <emphasis>must</emphasis> be defined,
 though.)
 </para>
 <para>
 As discussed in the previous chapter, three derived types are
-available for definition and use by <acronym>API</acronym>s: a
+available for definition and use by interfaces: a
 <type>structured</type> type can be defined with a <sgmltag
 class='element'>struct</sgmltag> element, an
 <type>enumeration</type> type can be defined with an <sgmltag
 class='element'>enum</sgmltag> element, and a <type>union</type>
 type can be defined with a <sgmltag
-class='element'>union</sgmltag> element.  <acronym>API</acronym>s
+class='element'>union</sgmltag> element.  Interfaces
-are defined using <sgmltag class='element'>api</sgmltag> elements.
+are defined using <sgmltag class='element'>interface</sgmltag> elements.
-The derived types defined in an interface document are available
+The derived types defined in an <acronym>API</acronym>
-for use by all <acronym>API</acronym>s defined in that document.
+document are available
-</para>
+for use by all interfaces defined in that document.
+</para>
-<example><title>Skeleton interface document</title>
-<programlisting><![CDATA[
+<example><title>Skeleton <acronym>API</acronym> document</title>
-<interface xmlns="http://xmlns.oracle.com/radadr" name="example">
+<programlisting><![CDATA[
+<api xmlns="http://xmlns.oracle.com/radadr" name="example">
 <struct>...</struct>
 <struct>...</struct>
 <enum>...</enum>
 <union>...</union>
-<api>...</api>
+<interface>...</interface>
-<api>...</api>
+<interface>...</interface>
-</interface>
+</api>
 ]]></programlisting>
 </example>
 </section>
 <section><title><type>enumeration</type> definitions</title>
 The <sgmltag class='element'>enum</sgmltag> element has a single
 <emphasis>mandatory</emphasis> attribute, <sgmltag
 class='attribute'>name</sgmltag>.  The <sgmltag
 class='attribute'>name</sgmltag> is used when referring to the
 <type>enumeration</type> from other derived type or
-<acronym>API</acronym> definitions.  An <sgmltag
+interface definitions.  An <sgmltag
 class='element'>enum</sgmltag> contains <emphasis>one or
 more</emphasis> <sgmltag class='element'>value</sgmltag> elements,
 one for each user-defined enumerated value.  A <sgmltag
 class='element'>value</sgmltag> element has a
 <emphasis>mandatory</emphasis> <sgmltag
 <sgmltag class='element'>struct</sgmltag> element has a single
 <emphasis>mandatory</emphasis> attribute, <sgmltag
 class='attribute'>name</sgmltag>.  The <sgmltag
 class='attribute'>name</sgmltag> is used when referring to the
 <type>structure</type> from other derived type or
-<acronym>API</acronym> definitions.  A <sgmltag
+interface definitions.  A <sgmltag
 class='element'>struct</sgmltag> contains <emphasis>one or
 more</emphasis> <sgmltag class='element'>field</sgmltag> elements,
 one for each field of the <type>structure</type>.  A <sgmltag
 class='element'>field</sgmltag> element has a
 <emphasis>mandatory</emphasis> <sgmltag
 <para>
 There are multiple ways to define the type of a field.  If a field
 is a plain base type, that type is defined with a
 <sgmltag class='attribute'>type</sgmltag> attribute.  If a field is
-a derived type defined elsewhere in the interface document, that
+a derived type defined elsewhere in the <acronym>API</acronym>
+document, that
 type is defined with a <sgmltag class='attribute'>typeref</sgmltag>
 attribute.  If a field is an <type>array</type> of some type (base
 or derived), that type is defined with a nested
 <sgmltag class='element'>list</sgmltag> element.  The type of the
 <type>array</type> is defined in the same fashion as the type of
 <sgmltag class='element'>arm</sgmltag> for that value is void.  The
 default <sgmltag class='element'>arm</sgmltag> is optional.
 </para>
 </section>
-<section><title><acronym>API</acronym> definitions</title>
+<section><title><acronym>Interface</acronym> definitions</title>
 <para>
-An <acronym>API</acronym> definition has a name, <emphasis>zero or
+An interface definition has a name, <emphasis>zero or
 more</emphasis> version specifications, and <emphasis>one or
 more</emphasis> attributes, methods, or events.  An
-<acronym>API</acronym>'s name is defined with the <sgmltag
+interface's name is defined with the <sgmltag
-class='element'>api</sgmltag> element's
+class='element'>interface</sgmltag> element's
 <emphasis>mandatory</emphasis> <sgmltag
-class='attribute'>name</sgmltag> attribute.  This name isn't
+class='attribute'>name</sgmltag> attribute.  This name is used
-referred to elsewhere in the interface document; it is used only in
+when referring to the (inherited) interface from other interface
+defintions, as well as in
 the server and various client environments.  The other
-characteristics of an <acronym>API</acronym> are defined using
+characteristics of an interface are defined using
-child elements of the <sgmltag class='element'>api</sgmltag>
+child elements of the <sgmltag class='element'>interface</sgmltag>
 element.
 </para>
 <section><title>Version</title>
 	<para>
-	An <acronym>API</acronym> <emphasis>may</emphasis> define one
+	An interface <emphasis>may</emphasis> define one
 	version for each commitment level.  It is not necessary to
 	define a version for every commitment level, but it is
 	recommended that one be specifed for every commitment level
-	assigned to the features defined in the <acronym>API</acronym>
+	assigned to the features defined in the interface
 	(i.e. the features defined in the enclosing <sgmltag
-	class='element'>api</sgmltag> element).
+	class='element'>interface</sgmltag> element).
 	</para>
 	<para>
 	A version is defined using a <sgmltag
 	class='element'>version</sgmltag> element.  The commitment
 	<!-- XXX: How is commitment specified? -->
 <section><title>Methods</title>
 	<para>
-	Each method in an <acronym>API</acronym> is defined by a
+	Each method in an interface is defined by a
 	<sgmltag class='element'>method</sgmltag> element.  The name of
 	a method is defined by this element's
 	<emphasis>mandatory</emphasis> <sgmltag
 	class='attribute'>name</sgmltag> attribute.  The other
 	properties of a method are defined by child elements of the
 </example>
 	</section>
 <section><title>Attributes</title>
 	<para>
-	Each attribute in an <acronym>API</acronym> is defined by a
+	Each attribute in an interface is defined by a
 	<sgmltag class='element'>property</sgmltag> element.  The name
 	of an attribute is defined by this element's
 	<emphasis>mandatory</emphasis> <sgmltag
 	class='attribute'>name</sgmltag> attribute.  The types of
 	access permitted are defined by the
 </example>
 	</section>
 <section><title>Events</title>
 	<para>
-	Each event in an <acronym>API</acronym> is defined by a
+	Each event in an interface is defined by a
 	<sgmltag class='element'>event</sgmltag> element.  The name of
 	an event is defined by this element's
 	<emphasis>mandatory</emphasis> <sgmltag
 	class='attribute'>name</sgmltag> attribute.  The type of an
 	event is specified in the same way the type is specified for a
 <section id="adr-idl.pragmas"><title>Pragmas</title>
 <para>
 Occasionally it is necessary to provide auxilliary information to a
 specific <acronym>ADR</acronym> consumer.  The
 <acronym>ADR</acronym> <acronym>IDL</acronym> has a pragma
-mechanism that lets an interface creator specify that information
+mechanism that lets an <acronym>API</acronym> creator specify that
+information
 in-line.
 </para>
 <para>
 A pragma is specified with a <sgmltag
 class='element'>pragma</sgmltag> child element of the <sgmltag
-class='element'>interface</sgmltag>.  A <sgmltag
+class='element'>api</sgmltag>.  A <sgmltag
 class='element'>pragma</sgmltag> has no child elements, and three
 <emphasis>mandatory</emphasis> attributes.  The <sgmltag
 class='attvalue'>domain</sgmltag> attribute indicates which
 consumer the pragma is intended for, and a <sgmltag
 class='attribute'>name</sgmltag> and a <sgmltag

changeset 865	025928ac8888
parent 842	abc3d63bd4da