Merge pull request ESMCI#1445 from NCAR/ejh_test

documentation fixes
jedwards4b · May 23, 2019 · 08d0dbc · 08d0dbc
2 parents 04234a4 + 09f7a51
commit 08d0dbc
Show file tree

Hide file tree

Showing 224 changed files with 2,271 additions and 7,600 deletions.
diff --git a/configure.ac b/configure.ac
@@ -253,6 +253,7 @@ AC_OUTPUT(Makefile
           tests/general/util/Makefile
           tests/performance/Makefile
           doc/Makefile
+          doc/source/Makefile
           examples/Makefile
           examples/c/Makefile
           scripts/Makefile)
diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -2,13 +2,16 @@
 
 # Ed Hartnett 4/1/19
 
-EXTRA_DIST = CMakeLists.txt customdoxygen.css Doxyfile.in	\
-DoxygenLayout.xml doxygen.sty
-
 # Run doxygen, then confirm warning log file is empty.
 check: all
 all:
 	doxygen Doxyfile
+	cat doxywarn.log
 	[ ! -s doxywarn.log ]
 
+SUBDIRS = source
+
 CLEANFILES = *.log
+
+EXTRA_DIST = CMakeLists.txt customdoxygen.css Doxyfile.in	\
+DoxygenLayout.xml doxygen.sty
diff --git a/doc/source/Makefile.am b/doc/source/Makefile.am
@@ -0,0 +1,8 @@
+# This is part of PIO. It creates the doc/source Makefile.
+
+# Ed Hartnett 5/20/19
+
+EXTRA_DIST = api.txt CAMexample.txt Decomp.txt faq.txt Installing.txt	\
+Testing.txt base.txt c_api.txt contributing_code.txt Error.txt		\
+Examples.txt GettingStarted.txt mach_walkthrough.txt			\
+testpio_example.txt
diff --git a/doc/source/api.txt b/doc/source/api.txt
@@ -1,14 +1,14 @@
- /*!  \page api PIO user interface
+ /*!  \page api PIO Fortran Interface
   This is a list of all user interface routines:
 
+  \section api_system PIO startup and shutdown routines
+     - \ref PIO_init
+     - \ref PIO_finalize
   \section api_fileops PIO file Operations
      - \ref PIO_openfile
      - \ref PIO_createfile
      - \ref PIO_syncfile
      - \ref PIO_closefile
-  \section api_system PIO startup and shutdown routines
-     - \ref PIO_init
-     - \ref PIO_finalize
   \section api_decomp PIO decomposition routines
     - \ref PIO_initdecomp
     - \ref PIO_freedecomp

diff --git a/doc/source/base.txt b/doc/source/base.txt
@@ -50,5 +50,6 @@ releases.
  - \ref examp
  - \ref faq
  - \ref api
+ - \ref c_api
  - \ref contributing_code
 */
diff --git a/doc/source/c_api.txt b/doc/source/c_api.txt
@@ -0,0 +1,44 @@
+ /*!  \page c_api PIO C Interface
+  This is a list of all user interface routines:
+
+  \section api_system_c PIO Startup and Shutdown
+     - \ref PIO_init_c
+     - \ref PIO_finalize_c
+  \section api_fileops_c PIO File Operations
+     - \ref PIO_open_file_c
+     - \ref PIO_create_file_c
+     - \ref PIO_sync_file_c
+     - \ref PIO_close_file_c
+  \section api_decomp_c PIO Decompositions
+    - \ref PIO_initdecomp_c
+    - \ref PIO_freedecomp_c
+  \section readwrite_c Reading and Writing Distributed Arrays
+    - \ref PIO_read_darray_c
+    - \ref PIO_write_darray_c
+    - \ref PIO_setframe_c
+  \section utility_c Utility 
+    - \ref PIO_set_hint_c
+    - \ref PIO_error_method_c
+    - \ref PIO_get_local_array_size_c
+    - \ref PIO_getnumiotasks_c
+    - \ref PIO_set_blocksize_c
+  \section netcdf_c NetCDF-Like Functions
+     Also see: http://www.unidata.ucar.edu/software/netcdf/docs/
+     \subsection utilnc_c File Operations
+       - \ref PIO_enddef_c
+       - \ref PIO_redef_c
+     \subsection write_metadata_c Writing Metadata   
+       - \ref PIO_def_dim_c
+       - \ref PIO_def_var_c
+       - \ref PIO_put_att_c
+     \subsection putget_c Reading/Writing Data
+       - \ref PIO_get_var_c
+       - \ref PIO_put_var_c
+     \subsection inqnc_c Learn about Files and Metadata
+       - \ref PIO_inq_c
+       - \ref PIO_get_att_c
+       - \ref PIO_inq_att_c
+       - \ref PIO_inq_var_c
+       - \ref PIO_inq_dim_c
+
+*/
diff --git a/docs/_c_a_mexample.html b/docs/_c_a_mexample.html
@@ -107,7 +107,7 @@ <h1><a class="anchor" id="Init"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

diff --git a/docs/annotated.html b/docs/annotated.html
diff --git a/docs/api.html b/docs/api.html
@@ -5,7 +5,7 @@
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.13"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
-<title>PIO: PIO user interface</title>
+<title>PIO: PIO Fortran Interface</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
@@ -61,10 +61,16 @@
 </div><!-- top -->
 <div class="header">
   <div class="headertitle">
-<div class="title">PIO user interface </div>  </div>
+<div class="title">PIO Fortran Interface </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>This is a list of all user interface routines:</p>
+<h1><a class="anchor" id="api_system"></a>
+PIO startup and shutdown routines</h1>
+<ul>
+<li><a class="el" href="group___p_i_o__init.html">PIO_init</a></li>
+<li><a class="el" href="group___p_i_o__finalize.html">PIO_finalize</a> </li>
+</ul>
 <h1><a class="anchor" id="api_fileops"></a>
 PIO file Operations</h1>
 <ul>
@@ -73,12 +79,6 @@ <h1><a class="anchor" id="api_fileops"></a>
 <li><a class="el" href="group___p_i_o__syncfile.html">PIO_syncfile</a></li>
 <li><a class="el" href="group___p_i_o__closefile.html">PIO_closefile</a> </li>
 </ul>
-<h1><a class="anchor" id="api_system"></a>
-PIO startup and shutdown routines</h1>
-<ul>
-<li><a class="el" href="group___p_i_o__init.html">PIO_init</a></li>
-<li><a class="el" href="group___p_i_o__finalize.html">PIO_finalize</a> </li>
-</ul>
 <h1><a class="anchor" id="api_decomp"></a>
 PIO decomposition routines</h1>
 <ul>
@@ -94,7 +94,7 @@ <h1><a class="anchor" id="readwrite"></a>
 <h1><a class="anchor" id="utility"></a>
 Utility routines</h1>
 <ul>
-<li><a class="el" href="group___p_i_o__set__hint.html">PIO_set_hint</a></li>
+<li><a class="el" href="group___p_i_o__set__hint__grp.html">PIO_set_hint</a></li>
 <li><a class="el" href="group___p_i_o__setframe.html">PIO_setframe</a></li>
 <li><a class="el" href="group___p_i_o__advanceframe.html">PIO_advanceframe</a></li>
 <li><a class="el" href="group___p_i_o__setdebuglevel.html">PIO_setdebuglevel</a></li>
@@ -129,7 +129,7 @@ <h2><a class="anchor" id="inqnc"></a>
 <li><a class="el" href="group___p_i_o__inq__attname.html">PIO_inq_attname</a></li>
 <li><a class="el" href="group___p_i_o__inq__att.html">PIO_inq_att</a></li>
 <li><a class="el" href="group___p_i_o__inq__attlen.html">PIO_inq_attlen</a></li>
-<li>PIO_inq_var</li>
+<li><a class="el" href="group___p_i_o__inquire__variable.html">PIO_inquire_variable</a></li>
 <li><a class="el" href="group___p_i_o__inq__varid.html">PIO_inq_varid</a></li>
 <li><a class="el" href="group___p_i_o__inq__varname.html">PIO_inq_varname</a></li>
 <li><a class="el" href="group___p_i_o__inq__vartype.html">PIO_inq_vartype</a></li>
@@ -149,7 +149,7 @@ <h2><a class="anchor" id="inqnc"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

diff --git a/docs/contributing_code.html b/docs/contributing_code.html
@@ -89,12 +89,209 @@ <h2>Indentation and Spacing</h2>
 <li>
 Indentation as defined by the "linux" style in emacs (see below). </li>
 <li>
-Use spaces around most operators (=+- </li>
+Use spaces around most operators (= + - * /) not pointer or prefix/postfile (* ++ &ndash;) </li>
+<li>
+Spaces after most keywords (if, for, while, etc.) </li>
+<li>
+No spaces after function name. </li>
+</ul>
+<h2>Braces</h2>
+<p>Put braces on their own line, avoiding their use if possible.</p>
+<h2>Documentation</h2>
+<ul>
+<li>
+Every function must be documented using doxygen. </li>
+<li>
+Keep internal functions in separate code files, so that Doxygen can easily build user and development builds of the documentation. </li>
+<li>
+Use the doxygen @ingroup to put public functions in the correct group. </li>
+<li>
+Code must be reasonably documented as to intention. </li>
+<li>
+Documentation quality and quantity are part of code review process. </li>
+<li>
+Document in complete sentences. </li>
+<li>
+Use C (not C++) comment delimiters. </li>
+<li>
+Use the author tag to indicate which programmers have worked on each function. When adding or changing a function in a non-trivial way, programmers should add their name to the end of the list of authors for that function. </li>
+</ul>
+<h2>Emacs</h2>
+<p>Put this in your .emacs file:</p>
+<pre>
+(setq c-default-style "linux"
+          c-basic-offset 4)
+</pre><p>The tab key (used anywhere on the line) will indent a line correctly. M-x indent-region will indent a selected region of code.</p>
+<p>M-x untabify will convert all the tabs in a file to spaces.</p>
+<h2>Code Review</h2>
+<ul>
+<li>
+<p class="startli">All code is subject to review.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Pull requests will be focused on one issue.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Pull requests may not be submitted until all tests pass.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">All non-trivial pull requests are associated with a github issue. The issue is where discussion of requirements and implementation details can be worked out.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Pull requests will be left up on github for about a day. Request more time if you need it and are actively reviewing the code. (Note that pull request can also be reviewed after they are merged, if you miss one).</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Jim will identify key stakeholders in changed code and ensure they accept code changes.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Reviewers are open-minded and ready to accept improvements to the library.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Reviewers will make comments on the pull request. All comments must be resolved.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">If chages are dictated, they happen on the branch, so code reviewers can see the updated code.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The pull request is only merged when all programmers agree that all issues have been resolved.</p>
+<p class="endli"></p>
+</li>
+</ul>
+<h2>Merge Proceedure</h2>
+<ul>
+<li>
+<p class="startli">Programmers begin work on a feature or fix by branching from develop.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">When a branch is ready, it is submitted to code review.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">When code review is complete, and the changes are approved, the PR is merged into the develop branch.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Mutliple merges into the develop branch may take place between test cycles. (???)</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The develop branch is tested automatically by Jenkins.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The develop branch is tested periodically by CDash (every ~6 hours).</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">After all jenkins and Cdash builds complete successfully, with all tests passing, and no warnings, the PR is merged into master by the integrator.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Multiple PRs may be merged to master between test cycles. (???)</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The branch is then deleted by whomever merged it to master.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The master branch is then tested on Jenkins.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The master branch is tested on CDash. Any test failures and the merge to master will be rolled back.</p>
+<p class="endli"></p>
+</li>
 </ul>
+<h2>Formatting Example</h2>
+<pre>
+/** 
+   @ingroup PIOc_inq_attname
+   The PIO-C interface for the NetCDF function nc_inq_attname.</pre><pre>   This routine is called collectively by all tasks in the communicator 
+   ios.union_comm. For more information on the underlying NetCDF commmand
+   please read about this function in the NetCDF documentation at: 
+   <a href="http://www.unidata.ucar.edu/software/netcdf/docs/group__attributes.html">http://www.unidata.ucar.edu/software/netcdf/docs/group__attributes.html</a></pre><pre>   @param ncid the ncid of the open file, obtained from
+   <a class="el" href="group___p_i_o__open__file__c.html#gae8e01fc5492663b46def2be31a95034c" title="Open an existing file using PIO library. ">PIOc_openfile()</a> or <a class="el" href="group___p_i_o__create__file__c.html#gaed31e065901c964d4224b3db61a30d5e" title="Create a new file using pio. ">PIOc_createfile()</a>.
+   @param varid the variable ID.
+   @param attnum the attribute ID.
+   @return PIO_NOERR for success, error code otherwise.  See PIOc_Set_File_Error_Handling
+ */
+int <a class="el" href="pio_8h.html#aa7d8b173e8bba7544c042301877082a0" title="The PIO-C interface for the NetCDF function nc_inq_attname. ">PIOc_inq_attname(int ncid, int varid, int attnum, char *name)</a> 
+{
+    <a class="el" href="structiosystem__desc__t.html" title="IO system descriptor structure. ">iosystem_desc_t</a> *ios;  /* Pointer to io system information. */
+    <a class="el" href="structfile__desc__t.html" title="File descriptor structure. ">file_desc_t</a> *file;     /* Pointer to file information. */
+    int ierr = PIO_NOERR;  /* Return code from function calls. */
+    int mpierr = MPI_SUCCESS, mpierr2;  /* Return code from MPI function codes. */</pre><pre>    LOG((1, "PIOc_inq_attname ncid = %d varid = %d attnum = %d", ncid, varid,
+         attnum));</pre><pre>    /* Find the info about this file. */
+    if (!(file = pio_get_file_from_id(ncid)))
+        return PIO_EBADID;
+    ios = file-&gt;iosystem;</pre><pre>    /* If async is in use, and this is not an IO task, bcast the parameters. */
+    if (ios-&gt;async_interface)
+    {
+        if (!ios-&gt;ioproc)
+        {
+            int msg = PIO_MSG_INQ_ATTNAME;
+            char name_present = name ? true : false;</pre><pre>            if(ios-&gt;compmaster) 
+                mpierr = MPI_Send(&amp;msg, 1,MPI_INT, ios-&gt;ioroot, 1, ios-&gt;union_comm);</pre><pre>            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;ncid, 1, MPI_INT, ios-&gt;compmaster, ios-&gt;intercomm);
+            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;varid, 1, MPI_INT, ios-&gt;compmaster, ios-&gt;intercomm);
+            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;attnum, 1, MPI_INT, ios-&gt;compmaster, ios-&gt;intercomm);
+            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;name_present, 1, MPI_CHAR, ios-&gt;compmaster, ios-&gt;intercomm);
+        }</pre><pre>        /* Handle MPI errors. */
+        if ((mpierr2 = MPI_Bcast(&amp;mpierr, 1, MPI_INT, ios-&gt;comproot, ios-&gt;my_comm)))
+            check_mpi(file, mpierr2, __FILE__, __LINE__);
+        if (mpierr)
+            return check_mpi(file, mpierr, __FILE__, __LINE__);
+    }</pre><pre>    /* If this is an IO task, then call the netCDF function. */
+    if (ios-&gt;ioproc)
+    {
+#ifdef _PNETCDF
+        if (file-&gt;iotype == PIO_IOTYPE_PNETCDF)
+            ierr = ncmpi_inq_attname(file-&gt;fh, varid, attnum, name);
+#endif /* _PNETCDF */
+#ifdef _NETCDF
+        if (file-&gt;iotype != PIO_IOTYPE_PNETCDF &amp;&amp; file-&gt;do_io)
+            ierr = nc_inq_attname(file-&gt;fh, varid, attnum, name);
+#endif /* _NETCDF */
+        LOG((2, "PIOc_inq_attname netcdf call returned %d", ierr));
+    }</pre><pre>    /* Broadcast and check the return code. */
+    if ((mpierr = MPI_Bcast(&amp;ierr, 1, MPI_INT, ios-&gt;ioroot, ios-&gt;my_comm)))
+    {
+        check_mpi(file, mpierr, __FILE__, __LINE__);            
+        return PIO_EIO;
+    }
+    check_netcdf(file, ierr, __FILE__, __LINE__);</pre><pre>    /* Broadcast results to all tasks. Ignore NULL parameters. */
+    if (!ierr)
+        if (name)
+        {
+            int namelen = strlen(name);
+            if ((mpierr = MPI_Bcast(&amp;namelen, 1, MPI_INT, ios-&gt;ioroot, ios-&gt;my_comm)))
+                check_mpi(file, mpierr, __FILE__, __LINE__);
+            if ((mpierr = MPI_Bcast((void *)name, namelen + 1, MPI_CHAR, ios-&gt;ioroot,
+                                    ios-&gt;my_comm)))
+                check_mpi(file, mpierr, __FILE__, __LINE__);
+        }</pre><pre>    return ierr;
+}
+</pre><h2>Further Information</h2>
+<p>For style issues not already covered in this document, see this <a href="https://www.kernel.org/doc/Documentation/CodingStyle">style guide</a>.</p>
+<p><em>Last updated: 05-16-2016</em> </p>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>