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>—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>
+<literal role="ndbapi">Table</literal>
+</programlisting>
+
+ <para>
+ Example 2: Each of the following 2 references links to the ID
+ <literal>ndb-table-singleusermode</literal>:
+ </para>
+
+<programlisting>
+<literal role="ndbapi">Table::SingleUserMode</literal>
+
+<literal role="ndbapi:Table">SingleUserMode</literal>
+</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>
+<literal role="ndbapi">Ndb_cluster_connection</literal>
+</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>
+<literal role="ndbapi">Ndb_cluster_connection::wait_until_ready()</literal>
+
+<literal role="ndbapi:Ndb_cluster_connection">wait_until_ready()</literal>
+</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-guide | jon.stephens | 10 Nov |
