List:Commits« Previous MessageNext Message »
From:jon.stephens Date:November 10 2010 12:38pm
Subject:svn commit - mysqldoc@docsrva: r23642 - trunk/mysqldoc-guide
View as plain text  
Author: jstephens
Date: 2010-11-10 13:38:13 +0100 (Wed, 10 Nov 2010)
New Revision: 23642

Log:

Add NDB API auto-link description and usage examples



Modified:
   trunk/mysqldoc-guide/special-markup.xml


Modified: trunk/mysqldoc-guide/special-markup.xml
===================================================================
--- trunk/mysqldoc-guide/special-markup.xml	2010-11-10 11:59:51 UTC (rev 23641)
+++ trunk/mysqldoc-guide/special-markup.xml	2010-11-10 12:38:13 UTC (rev 23642)
Changed blocks: 3, Lines Added: 120, Lines Deleted: 6; 5987 bytes

@@ -877,12 +877,19 @@
           <literal>isolevel</literal> for a transaction isolation level,
           <literal>cfunc</literal> for a C API function,
           <literal>jointype</literal> for an optimizer join type (as
-          seen in <literal>EXPLAIN</literal> output), or
-          <literal>priv</literal> for an access privilege. For MySQL
-          Cluster configuration parameters, the <literal>role</literal>
-          value starts with the prefix <literal>ndbparam:</literal>;
-          this is explained further later in this section.
+          seen in <literal>EXPLAIN</literal> output),
+          <literal>priv</literal> for an access privilege, or
+          <literal>ndbapi</literal> (or possibly
+          <literal>ndbapi:<replaceable>$class_name</replaceable></literal>&mdash;see
+          below) for an NDB API class, class member, type, or struct.
         </para>
+
+        <para>
+          Auto-linking of MySQL Cluster configuration parameters is also
+          supported. For these, the <literal>role</literal> value starts
+          with the prefix <literal>ndbparam:</literal>; this is
+          explained further later in this section.
+        </para>
       </listitem>
 
       <listitem>

@@ -1105,6 +1112,112 @@
 
       <listitem>
         <para>
+          NDB API class, class member, type, or struct (MySQL Cluster):
+          First, replace any underscores in the element text with
+          dashes, and remove any parentheses (we refer to this modified
+          string as <replaceable>$dashes</replaceable> hereafter).
+        </para>
+
+        <para>
+          If the <literal>role</literal> attribute does
+          <emphasis>not</emphasis> contain a ':' character, handle as
+          follows:
+        </para>
+
+        <para>
+          Does <replaceable>$dashes</replaceable> contain the string
+          '::'? If not, use the entire text of
+          <replaceable>$dashes</replaceable> for the ID; that is, we
+          assume the original element text is the name of an NDB API
+          class or struct. Otherwise (if
+          <replaceable>$dashes</replaceable> <emphasis>does</emphasis>
+          contain '::'), replace '::' with a dash and use this for the
+          ID.
+        </para>
+
+        <para>
+          If the <literal>role</literal> attribute
+          <emphasis>does</emphasis> contain a colon character (':'),
+          handle as follows:
+        </para>
+
+        <para>
+          We assume that the element text is the unqualified name of a
+          class member. In this case, the name of the parent class is
+          supplied in the <literal>role</literal> as the portion
+          following the colon; we can represent the entire role
+          attribute value as
+          <literal>ndbapi:<replaceable>$class</replaceable></literal>.
+          We split <replaceable>$class</replaceable> from the
+          <literal>role</literal> attribute, then convert
+          <replaceable>$class</replaceable> to lowercase and replace any
+          underscores it contains to dashes. We use the result of this
+          conversion, followed by a dash, and then by
+          <replaceable>$dashes</replaceable> as the ID.
+        </para>
+
+        <para>
+          Finally, we prefix the ID obtained previously with
+          <literal>ndb-</literal>.
+        </para>
+
+        <para>
+          Example 1: The following reference links to the ID
+          <literal>ndb-table</literal>:
+        </para>
+
+<programlisting>
+&lt;literal role="ndbapi"&gt;Table&lt;/literal&gt;
+</programlisting>
+
+        <para>
+          Example 2: Each of the following 2 references links to the ID
+          <literal>ndb-table-singleusermode</literal>:
+        </para>
+
+<programlisting>
+&lt;literal role="ndbapi"&gt;Table::SingleUserMode&lt;/literal&gt;
+
+&lt;literal role="ndbapi:Table"&gt;SingleUserMode&lt;/literal&gt;
+</programlisting>
+
+        <para>
+          In the second case just shown, the name of the parent class
+          (<literal>Table</literal>) is supplied as part of the
+          <literal>role</literal> attribute.
+        </para>
+
+        <para>
+          Example 3: The following reference links to the ID
+          <literal>ndb-ndb-cluster-connection</literal> (note that
+          <literal>ndb-ndb-</literal> is not a typo!):
+        </para>
+
+<programlisting>
+&lt;literal role="ndbapi"&gt;Ndb_cluster_connection&lt;/literal&gt;
+</programlisting>
+
+        <para>
+          Example 4: Each of the following 2 references links to the ID
+          <literal>ndb-ndb-cluster-connection-wait-until-ready</literal>
+          (again, <literal>ndb-ndb-</literal> is correct):
+        </para>
+
+<programlisting>
+&lt;literal role="ndbapi"&gt;Ndb_cluster_connection::wait_until_ready()&lt;/literal&gt;
+
+&lt;literal role="ndbapi:Ndb_cluster_connection"&gt;wait_until_ready()&lt;/literal&gt;
+</programlisting>
+
+        <para>
+          In the second case just shown, the name of the parent class
+          (<literal>Ndb_cluster_connection</literal>) is supplied as
+          part of the <literal>role</literal> attribute.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
           MySQL Cluster configuration parameter: The
           <literal>role</literal> is constructed and used somewhat
           differently from the others just described. A configuration

@@ -1158,7 +1271,8 @@
               <row>
                 <entry><literal>shm</literal></entry>
                 <entry><literal>tcp</literal></entry>
-                <entry><literal>system</literal></entry>
+                <entry><literal>system</literal> (<emphasis>not currently used or supported for
+                  end users</emphasis>)</entry>
               </row>
             </tbody>
           </tgroup>


Thread
svn commit - mysqldoc@docsrva: r23642 - trunk/mysqldoc-guidejon.stephens10 Nov