Aren/haiku
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Last commit before Christmas.

Browse Source 
Added skeleton of Archivable and Flattenable. Updated howo on how to handle static functions and pure virtuals.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@19613 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk 2006-12-23 21:12:43 +00:00
parent c67edfe303
commit 0e91b5924a
6 changed files with 303 additions and 11 deletions

29
src/documentation/haiku_book/howto.xml

@ -26,7 +26,7 @@
<revhistory>
<revision>
<revnumber>1</revnumber>
<date>2005-10-26</date>
<date>2005-12-23</date>
<authorinitials>nielx</authorinitials>
<revremark>First section about documenting classes on review.</revremark>
</revision>
@ -236,9 +236,10 @@
<para>
We can distinguish roughly three parts. First of all, we've got the class
summary. This includes a formal block with useful information. Secondly,
we document the constructors and destructors. Then we describe
we document the constructors and destructors. Thirdly, we describe the static
members that the class might have. Then we describe
the member functions. Finally we describe the operators that are overloaded.
Note that any section can be left out if it's not available. For example, the
Note that any section can be left out if it's not applicable. For example, the
<classname>BList</classname> class doesn't have actual overloaded operators,
thus that section is not in the actual documentation. The following example
gives a rough outline of the <classname>BList</classname> documentation.
@ -260,6 +261,10 @@
... constructors come here ...
&lt;bridgehead renderas="sect2"&gt;Static Functions&lt;/bridgehead&gt;
... member functions come here ...
&lt;bridgehead renderas="sect2"&gt;Member Functions&lt;/bridgehead&gt;
... member functions come here ...
@ -415,13 +420,15 @@
</para>
</sect3>
<sect3 id="methoddescriptions">
<title>Member documentation</title>
<title>Static and Member documentation</title>
<para>
The member documentation starts under the second
Static documentation starts under the second
<literal>&lt;bridgehead&gt;</literal> with the label
<quote>Member Functions</quote>. This <literal>&lt;bridgehead&gt;</literal>
has the same properties as the one the one used with the constructors.
<quote>Static Functions</quote>. The member functions start under
<quote>Member Functions</quote>. These <literal>&lt;bridgehead&gt;</literal>
have the same properties as the one the one used with the constructors.
Note that either section can be left out if they are not applicable.
</para>
<para>
@ -699,8 +706,12 @@
<listitem><para>
The last thing you need to be aware of is whether or not the method is
modified by a trailing <literal>const</literal>. If so, you need to append
<literal>&lt;modifier&gt;const&lt;/modifier&gt;</literal>. The location
modified by a trailing <literal>const</literal>, or if the method is a pure
virtual. If so, you need to append either
<literal>&lt;modifier&gt;const&lt;/modifier&gt;</literal> or
<literal>&lt;modifier&gt;= 0&lt;/modifier&gt;</literal>. Please note the
space between the <quote>=</quote> and the <quote>0</quote> in the
syntax for the pure virtuals. The location of this modifier
depends on whether or not the method has arguments. If it doesn't have
any arguments, just append it to the single line you've written. If there are
arguments, put this on a newline after the last argument.

60
src/documentation/haiku_book/support/Archivable.xml Normal file

@ -0,0 +1,60 @@
<?xml version="1.0" encoding="UTF-8"?>
<sect2 id="barchivable">
<title>BArchivable</title>
<itemizedlist>
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/Archivable.h</filename></para></listitem>
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
</itemizedlist>
<para><classname>BArchivable</classname> works on archiving and unarchiving BMessages.</para>
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
<sect3 id="barchivable_constructor">
<title>BArchivable()</title>
<constructorsynopsis>
<methodname>BArchivable</methodname>
</constructorsynopsis>
<constructorsynopsis>
<methodname>BArchivable</methodname>
<methodparam><type>BMessage *</type><parameter>from</parameter></methodparam>
</constructorsynopsis>
</sect3>
<sect3 id="barchivable_destructor">
<title>~BArchivable()</title>
<destructorsynopsis>
<methodname>~BArchivable</methodname>
</destructorsynopsis>
</sect3>
<bridgehead renderas="sect2">Static Functions</bridgehead>
<sect3 id="barchivable_instantiate">
<title>Instantiate()</title>
<methodsynopsis>
<modifier>static</modifier><type>BArchivable *</type><methodname>Instatiate</methodname>
<methodparam><type>BMessage *</type><parameter>from</parameter></methodparam>
</methodsynopsis>
</sect3>
<bridgehead renderas="sect2">Member Functions</bridgehead>
<sect3 id="archive">
<title>Archive()</title>
<methodsynopsis>
<modifier>virtual</modifier><type>status_t</type><methodname>Archive</methodname>
<methodparam><type>BMessage *</type><parameter>into</parameter></methodparam>
<methodparam><type>bool</type><parameter>deep</parameter><initializer>true</initializer></methodparam>
<modifier>const</modifier>
</methodsynopsis>
</sect3>
</sect2>

82
src/documentation/haiku_book/support/Flattenable.xml Normal file

@ -0,0 +1,82 @@
<?xml version="1.0" encoding="UTF-8"?>
<sect2 id="bflattenable">
<title>BFlattenable</title>
<itemizedlist>
<listitem><para><emphasis>Derived from:</emphasis> none</para></listitem>
<listitem><para><emphasis>Declared in:</emphasis> <filename>os/support/Flattenable.h</filename></para></listitem>
<listitem><para><emphasis>Library:</emphasis> <filename>libbe.so</filename></para></listitem>
</itemizedlist>
<para><classname>BFlattenable</classname> is a protocol that classes can implement so that they can be written to a stream of bytes.</para>
<bridgehead renderas="sect2">Constructors and Destructors</bridgehead>
<sect3 id="bflattenable_destructor">
<title>~BFlattenable</title>
<destructorsynopsis>
<modifier>virtual</modifier><methodname>~BFlattenable</methodname>
</destructorsynopsis>
</sect3>
<bridgehead renderas="sect2">Member Functions</bridgehead>
<sect3 id="bflattenable_allowstypecode">
<title>AllowsTypeCode()</title>
<methodsynopsis>
<modifier>virtual</modifier><type>bool</type><methodname>AllowsTypeCode</methodname>
<methodparam><type>type_code</type><parameter>code</parameter></methodparam>
<modifier>= 0</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bflattenable_flatten">
<title>Flatten()</title>
<methodsynopsis>
<modifier>virtual</modifier><type>status_t</type><methodname>Flatten</methodname>
<methodparam><type>void *</type><parameter>buffer</parameter></methodparam>
<methodparam><type>ssize_t</type><parameter>size</parameter></methodparam>
<modifier>const</modifier><modifier>= 0</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bflattenable_flattenedsize">
<title>FlattenedSize()</title>
<methodsynopsis>
<modifier>virtual</modifier><type>ssize_t</type><methodname>FlattenedSize</methodname><modifier>const</modifier><modifier>= 0</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bflattenable_isfixedsize">
<title>IsFixedSize()</title>
<methodsynopsis>
<modifier>virtual</modifier><type>bool</type><methodname>IsFixedSize</methodname><modifier>const</modifier><modifier>= 0</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bflattenable_typecode">
<title>TypeCode()</title>
<methodsynopsis>
<modifier>virtual</modifier><type>type_code</type><methodname>TypeCode</methodname><modifier>const</modifier><modifier>= 0</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bflattenable_unflatten">
<title>Unflatten</title>
<methodsynopsis>
<modifier>virtual</modifier><type>status_t</type><methodname>Unflatten</methodname>
<methodparam><type>type_code</type><parameter>c</parameter></methodparam>
<methodparam><modifier>const</modifier><type>void *</type><parameter>buf</parameter></methodparam>
<methodparam><type>ssize_t</type><parameter>size</parameter></methodparam>
<modifier>= 0</modifier>
</methodsynopsis>
</sect3>
</sect2>

135
src/documentation/haiku_book/support/String.xml

@ -92,6 +92,36 @@
</methodsynopsis>
</sect3>
<sect3 id="bstring_compare">
<title>Compare()</title>
<methodsynopsis>
<type>int</type><methodname>Compare</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>Compare</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>Compare</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>Compare</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bstring_copyinto">
<title>CopyInto()</title>
@ -118,6 +148,36 @@
</methodsynopsis>
</sect3>
<sect3 id="bstring_icompare">
<title>ICompare()</title>
<methodsynopsis>
<type>int</type><methodname>ICompare</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>ICompare</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>ICompare</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>int</type><methodname>ICompare</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<methodparam><type>int32</type><parameter>n</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
</sect3>
<sect3 id="bstring_insert">
<title>Insert()</title>
@ -379,4 +439,79 @@
</methodsynopsis>
</sect3>
<sect3 id="bstring_operator_comparison">
<title>&lt;, &lt;=, ==, &gt;, &gt;=, != (comparison)</title>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&lt;</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&lt;</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&lt;=</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&lt;=</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator==</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator==</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&gt;=</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&gt;=</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&gt;</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator&gt;</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator!=</methodname>
<methodparam><modifier>const</modifier><type>BString &amp;</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
<methodsynopsis>
<type>BString &amp;</type><methodname>operator!=</methodname>
<methodparam><modifier>const</modifier><type>char *</type><parameter>string</parameter></methodparam>
<modifier>const</modifier>
</methodsynopsis>
</sect3>
</sect2>

4
src/documentation/haiku_book/support/api.xml

@ -2,8 +2,10 @@
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY archivable SYSTEM "Archivable.xml">
<!ENTITY autolock SYSTEM "Autolock.xml">
<!ENTITY blockcache SYSTEM "BlockCache.xml">
<!ENTITY flattenable SYSTEM "Flattenable.xml">
<!ENTITY list SYSTEM "List.xml">
<!ENTITY locker SYSTEM "Locker.xml">
<!ENTITY string SYSTEM "String.xml">
@ -13,8 +15,10 @@
<sect1 id="supportapi">
<title>Support Kit API</title>
&archivable;
&autolock;
&blockcache;
&flattenable;
&list;
&locker;
&string;

4
src/documentation/haiku_book/support/intro.xml

@ -20,8 +20,8 @@
<listitem><para>
Archiving and IO:
<itemizedlist>
<listitem><para> BArchivable </para></listitem>
<listitem><para> BFlattenable </para></listitem>
<listitem><para><link linkend="barchivable">BArchivable</link></para></listitem>
<listitem><para><link linkend="bflattenable">BFlattenable</link></para></listitem>
<listitem><para> BDataIO and BPositionIO </para></listitem>
<listitem><para> BMemoryIO and BMallocIO </para></listitem>
</itemizedlist>