[svn-r467] Restructuring documentation.

author: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
committer: Quincey Koziol <koziol@hdfgroup.org> 1998-07-08 14:54:54 (GMT)
commit: bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree: 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Coding.html
parent: 73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download: hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz
hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2
1 files changed, 300 insertions, 0 deletions
diff --git a/doc/html/Coding.html b/doc/html/Coding.html
new file mode 100644
index 0000000..dbf55bf
--- /dev/null
+++ b/doc/html/Coding.html
@@ -0,0 +1,300 @@
+<HTML>
+<HEAD><TITLE>
+             HDF5 Naming Scheme
+      </TITLE> </HEAD>
+
+<BODY bgcolor="#ffffff">
+  
+
+<H1>
+<FONT color="#c80028"
+ <I> <B> <CENTER>  HDF5 Naming Scheme for </CENTER> </B> </I> </H1>
+</FONT>
+<P>
+<UL>
+
+<LI>       <A HREF = "#01"><I>  FILES </I> </A>
+<LI>       <A HREF = "#02"><I>  PACKAGES </I> </A>
+<LI>       <A HREF = "#03"><I>  PUBLIC vs PRIVATE </I> </A>
+<LI>       <A HREF = "#04"><I>  INTEGRAL TYPES </I> </A>
+<LI>       <A HREF = "#05"><I>  OTHER TYPES </I> </A>
+<LI>       <A HREF = "#06"><I>  GLOBAL VARIABLES </I> </A>
+<LI>       <A HREF = "#07"><I>  MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMEBERs </I> </A>
+
+</UL>
+<P>
+<center>
+	 Authors: <A HREF = "mailto:koziol@ncsa.uiuc.edu">
+        <I>Quincey Koziol</I> </A> and 
+                  <A HREF = "mailto:matzke@llnl.gov">   
+        <I>		  Robb Matzke </I> </A>   
+
+</center>
+<UL>
+
+<FONT color="#c80028"
+<LI> <A NAME="01">  <B> <I> FILES </I> </B>  </A>
+</FONT>
+
+<UL>
+
+  <LI>  Source files are named according to the package they contain (see
+    below).  All files will begin with `H5' so we can stuff our
+    object files into someone else's library and not worry about file
+    name conflicts.
+  <P>For Example:
+<i><b>
+<dd>	H5.c		-- "Generic" library functions 
+   <br>
+<dd>	H5B.c		-- B-link tree functions
+</i></b>
+  <p>
+   <LI> If a package is in more than one file, then another name is tacked
+    on.  It's all lower case with no underscores or hyphens.
+   <P>For Example:
+<i><b>
+<dd>	H5F.c		-- the file for this package
+   <br>
+<dd>	H5Fstdio.c	-- stdio functions (just an example)
+   <br>
+<dd>	H5Ffcntl.c	-- fcntl functions (just an example)
+</i></b>
+   <p>
+  <LI> Each package file has a header file of API stuff (unless there is
+    no API component to the package)
+   <P>For Example:
+<i><b>
+<dd>	H5F.h		-- things an application would see. </i> </b>
+   <P>
+    and a header file of private stuff
+<i><b>
+   <p>
+<dd>	H5Fprivate.h	-- things an application wouldn't see. The
+                    	   private header includes the public header.
+</i></b>
+    <p>
+    and a header for private prototypes
+<i><b>
+   <p>
+<dd>	H5Fproto.h	-- prototypes for internal functions.
+</i></b>
+    <P>
+    By splitting the prototypes into separate include files we don't
+    have to recompile everything when just one function prototype
+    changes.
+
+   <LI> The main API header file is `hdf5.h' and it includes each of the
+    public header files but none of the private header files.  Or the
+    application can include just the public header files it needs.
+
+   <LI> There is no main private or prototype header file because it
+    prevents make from being efficient.  Instead, each source file
+    includes only the private header and prototype files it needs
+    (first all the private headers, then all the private prototypes).
+
+   <LI> Header files should include everything they need and nothing more.
+
+</UL>
+<P>
+
+<FONT color="#c80028"
+<LI> <A NAME="02">  <B> <I> PACKAGES </I> </B>  </A>
+</FONT>
+
+<P>
+Names exported beyond function scope begin with `H5' followed by zero,
+one, or two upper-case letters that describe the class of object.
+This prefix is the package name.  The implementation of packages
+doesn't necessarily have to map 1:1 to the source files.
+<P>
+<i><b>
+<dd>	H5	-- library functions
+<br>
+<dd>	H5A	-- atoms
+<br>
+<dd>	H5AC	-- cache
+<br>
+<dd>	H5B	-- B-link trees
+<br>
+<dd>	H5D	-- datasets
+<br>
+<dd>	H5E	-- error handling
+<br>
+<dd>	H5F	-- files
+<br>
+<dd>	H5G	-- groups
+<br>
+<dd>	H5M	-- meta data
+<br>
+<dd>	H5MM	-- core memory management
+<br>
+<dd>	H5MF	-- file memory management
+<br>
+<dd>	H5O	-- object headers
+<br>
+<dd>	H5P	-- Property Lists
+<br>
+<dd>	H5S	-- dataspaces
+<br>
+<dd>	H5R	-- relationships
+<br>
+<dd>	H5T	-- datatype
+</i></b>
+<p>
+Each package implements a single main class of object (e.g., the H5B
+package implements B-link trees).  The main data type of a package is
+the package name followed by `_t'.
+<p>
+<i><b>
+<dd>	H5F_t		-- HDF5 file type
+<br>
+<dd>	H5B_t		-- B-link tree data type
+</i></b>
+<p>
+
+Not all packages implement a data type (H5, H5MF) and some
+packages provide access to a preexisting data type (H5MM, H5S).
+<p>
+
+
+<FONT color="#c80028"
+<LI> <A NAME="03">  <B> <I> PUBLIC vs PRIVATE </I> </B>  </A>
+</FONT>
+<p>
+If the symbol is for internal use only, then the package name is
+followed by an underscore and the rest of the name.  Otherwise, the
+symbol is part of the API and there is no underscore between the
+package name and the rest of the name.
+<p>
+<i><b>
+<dd>	H5Fopen		-- an API function.
+<br>
+<dd>	H5B_find	-- an internal function.
+</i></b>
+<p>
+For functions, this is important because the API functions never pass
+pointers around (they use atoms instead for hiding the implementation)
+and they perform stringent checks on their arguments.  Internal
+unctions, on the other hand, check arguments with assert().
+<p>
+Data types like H5B_t carry no information about whether the type is
+public or private since it doesn't matter.
+
+<p>
+
+
+<FONT color="#c80028"
+<LI> <A NAME="04"> <B> <I> INTEGRAL TYPES </I> </B>  </A>
+</FONT>
+<p>
+Integral fixed-point type names are an optional `u' followed by `int'
+followed by the size in bits (8, 16,
+32, or 64).  There is no trailing `_t' because these are common
+enough and follow their own naming convention.
+<p>
+<pre><H4>
+<dd>	hbool_t     -- boolean values (BTRUE, BFALSE, BFAIL)
+<br>
+<dd>	int8		-- signed 8-bit integers
+<br>
+<dd>	uint8       -- unsigned 8-bit integers
+<br>
+<dd>	int16       -- signed 16-bit integers
+<br>
+<dd>	uint16      -- unsigned 16-bit integers
+<br>
+<dd>	int32       -- signed 32-bit integers
+<br>
+<dd>	uint32      -- unsigned 32-bit integers
+<br>
+<dd>	int64       -- signed 64-bit integers
+<br>
+<dd>	uint64      -- unsigned 64-bit integers
+<br>
+<dd>	intn		-- "native" integers
+<br>
+<dd>	uintn		-- "native" unsigned integers
+
+</pre></H4>
+<p>
+
+<FONT color="#c80028"
+<LI> <A NAME="05"> <B> <I> OTHER TYPES </I> </B> </A>
+</FONT>
+
+<p>
+
+Other data types are always followed by `_t'.
+<p>
+<pre><H4>
+<dd>	H5B_key_t-- additional data type used by H5B package.
+</pre></H4>
+<p>
+
+However, if the name is so common that it's used almost everywhere,
+then we make an alias for it by removing the package name and leading
+underscore and replacing it with an `h'  (the main datatype for a
+package already has a short enough name, so we don't have aliases for
+them).
+<P>
+<pre><H4>
+<dd>	typedef H5E_err_t herr_t;
+</pre> </H4>
+<p>
+
+<FONT color="#c80028"
+<LI> <A NAME="06">  <B> <I> GLOBAL VARIABLES </I> </B>  </A>
+</FONT>
+<p>
+Global variables include the package name and end with `_g'.
+<p>
+<pre><H4>
+<dd>	H5AC_methods_g	-- global variable in the H5AC package.
+</pre> </H4>
+<p>
+
+
+<FONT color="#c80028"
+<LI> <A NAME="07">   
+<I> <B>
+MACROS, PREPROCESSOR CONSTANTS, AND ENUM MEMBERS
+  </I> </B>  </A>
+</FONT>
+<p>
+Same rules as other symbols except the name is all upper case.  There
+are a few exceptions: <br>
+<ul>
+<li>	Constants and macros defined on a system that is deficient: 
+       <p><pre><H4> 
+<dd>		MIN(x,y), MAX(x,y) and their relatives
+        </pre></H4>
+
+<li>	Platform constants :
+       <P> 
+		No naming scheme; determined by OS and compiler.<br>
+		These appear only in one header file anyway.
+        <p>
+<li>	Feature test constants (?)<br>
+		Always start with `HDF5_HAVE_' like HDF5_HAVE_STDARG_H for a
+		header file, or HDF5_HAVE_DEV_T for a data type, or
+		HDF5_HAVE_DIV for a function.
+</UL>
+<p>
+
+</UL>
+<p>
+<H6>
+<center>
+	 This file /hdf3/web/hdf/internal/HDF_standard/HDF5.coding_standard.html is
+	 maintained by Elena Pourmal <A HREF = "mailto:epourmal@ncsa.uiuc.edu">
+         <I>epourmal@ncsa.uiuc.edu</I> </A>.
+</center>
+<p>
+<center>
+          Last modified August 5, 1997
+</center>
+
+</H6>
+</BODY>
+<HTML>
+
author	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
committer	Quincey Koziol <koziol@hdfgroup.org>	1998-07-08 14:54:54 (GMT)
commit	bd1e676c521d881b3143829f493a28b5ced1294b (patch)
tree	69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Coding.html
parent	73345095897d9698bb1f2f7df830bf80a56dc65a (diff)
download	hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2