more documentation, fixed bug in reanttweakbar

Former-commit-id: 85afd134fe16f83b3a0cd1d332a1fc3481b8eddd

examples/ReAntTweakBar/Makefile

@@ -12,7 +12,7 @@ IGL=../../
 
 ANTTWEAKBAR_INC=-I$(IGL)/external/AntTweakBar/include
 ANTTWEAKBAR_LIB=-L$(IGL)/external/AntTweakBar/lib -lAntTweakBar -framework AppKit
-inc=-I$(IGL)/include -I$(DEFAULT_PREFIX)/include $(ANTTWEAKBAR_INC)
+inc=-DIGL_HEADER_ONLY -I$(IGL)/include -I$(DEFAULT_PREFIX)/include $(ANTTWEAKBAR_INC)
 lib=-L$(IGL)/lib -ligl -L$(DEFAULT_PREFIX)/lib $(OPENGL_LIB) $(GLUT_LIB) $(ANTTWEAKBAR_LIB)
 
 example: example.o

include/igl/ReAntTweakBar.h

@@ -44,7 +44,6 @@
 
 #include <vector>
 #include <string>
-#include <cassert>
 
 namespace igl
 {
@@ -68,19 +67,17 @@ namespace igl
     {
     }
     // Shallow copy constructor
+    // I solemnly swear it's OK to copy var this way
     ReTwRWItem(const ReTwRWItem & that):
       name(that.name),
       type(that.type),
       var(that.var)
     {
-      // I don't think you should be using this!
-      assert(false);
     }
     // Shallow assignment 
+    // I solemnly swear it's OK to copy var this way
     ReTwRWItem & operator=(const ReTwRWItem & that)
     {
-      // I don't think you should be using this!
-      assert(false);
       if(this != &that)
       {
         this->name = that.name;
@@ -114,6 +111,7 @@ namespace igl
     {
     }
     // Shallow copy
+    // I solemnly swear it's OK to copy clientData this way
     ReTwCBItem(const ReTwCBItem & that):
       name(that.name),
       type(that.type),
@@ -121,14 +119,11 @@ namespace igl
       getCallback(that.getCallback),
       clientData(that.clientData)
     {
-      // I don't think you should be using this!
-      assert(false);
     }
     // Shallow assignment
+    // I solemnly swear it's OK to copy clientData this way
     ReTwCBItem & operator=(const ReTwCBItem & that)
     {
-      // I don't think you should be using this!
-      assert(false);
       if(this != &that)
       {
         name = that.name;

include/igl/doublearea.h

@@ -18,6 +18,8 @@ namespace igl
   //   F  #F by simplex_size list of mesh faces (must be triangles)
   // Outputs:
   //   dblA  #F list of triangle double areas
+  //
+  // Note: THESE ARE *NOT* SIGNED. In matlab doublearea is signed in 2d
   template <typename DerivedV, typename DerivedF, typename DeriveddblA>
   IGL_INLINE void doublearea( 
     const Eigen::PlainObjectBase<DerivedV> & V, 

include/igl/example_fun.cpp

@@ -1,4 +1,4 @@
-#include "igl/example_fun.h"
+#include "example_fun.h"
 #include <iostream>
 
 template <typename Printable>

readme.txt

@@ -1,124 +1,11 @@
-e gl Library - A simple c++ mesh library
-Copyright 2011 - Daniele Panozzo, Alec Jacobson, Olga Diamanti
+IGL Library - A simple c++ geometry processing library
+Copyright 2013 - Alec Jacobson, Daniele Panozzo, Olga Diamanti, Kenshi
+Takayama, Leo Sacht
 Interactive Geometry Lab - ETH Zurich
 
-This is a *header* library. Each header file should contain a single
-function. The function may have multiple prototypes. All functions
-should use the igl namespace and should adhere to the conventions and
-styles listed below. 
-
-= Example =
-The following is a toy example of a function called example() in the
-file example.h:
-
-#ifndef IGL_EXAMPLE_H
-#define IGL_EXAMPLE_H
-namespace igl
-{
-  // An example function that prints "Hello, world"
-  inline void example();
-}
-
-// Implementation
-#include <iostream>
-inline void igl::example()
-{
-  std::cout<<"Hello, world"<<std::endl;
-}
-
-= Standards =
-
-This library is shared by many people. Each function prototype should be
-well documented.  Write a summary of what the function does and a
-description of each template, input and output in each prototype. 
-
-  X- All functions must be inlined, otherwise there is trouble when
-    linking included headers used in multiple .cpp files
-  - Use a single .h/.cpp pair with the same name as the function
-  X- Do *not* use any .cpp files (this is *header only* library)
-  - At least one version of the function should use references for all
-    outputs
-  - Functions with external dependencies should be a single .h file (no
-    .cpp file) so it won't appear in libigl.a
-  - Use wrappers and additional prototypes for returning single-output
-    functions' outputs, but the default is to only use outputs
-  - All inputs should be const when appropriate
-  - Use c++ references for inputs and outputs rather than pointers or
-    pass-by-copy
-  - Take the time to write multiple prototypes if you'd like to have
-    optional parameters with default values
-  - External dependencies (besides Eigen, OpenGL, etc.) are discouraged
-  - External dependencies must be clearly identified at the top of each
-    file.
-  - Single header external dependencies can go in the external/
-    directory
-  - Do not use the using namespace directive anywhere. This means never
-    write:
-    "using namespace std;"
-     or 
-    "using namespace igl;"
-    etc.
-  - Function names should either be the same as the corresponding MATLAB
-    function or should use all lowercase separated by underscores: e.g.
-    my_function_name
-  - Classes should be in CamelCase
-  - No tabs, only two spaces per indentation level
-
-  = Specific style conventions =
-
-  Each file should be wrapped in an ifndef compiler directive. If the
-  file's (and function's) name is example.h, then the ifndef should
-  always begin with IGL_, then the function/file name in all caps then
-  _H. As in:
-#ifndef IGL_EXAMPLE_H
-#define IGL_EXAMPLE_H
-...
-#endif
-  
-  Each file should begin with prototypes *without implementations* of
-  each version of the function. All defined in the igl namespace. Each
-  prototype should have its own comments describing what it is doing,
-  and its templates, inputs, outputs.
-
-  Implementations should be at the end of each file, separated from the
-  prototypes using:
-// Implementation
-
-  Any includes, such as std libraries etc. should come after
-  the //Implementation separator (whenever feasibly possible).
-
-  Be generous by templating your inputs and outputs. If you do use
-  templates, you must document the template just as you document inputs
-  and outputs.
-
-  = Useful checks =
-  
-  Find files that aren't using "inline"
-
-    grep -L inline *
-
-  Find files that aren't using igl namespace
-
-    grep -L "namespace igl" *
-
-  Find files using [TAB] character
-
-    grep -P '\t' *
-
-  Find files that don't contain // Implementation
-
-    grep -L "^\/\/ Implementation" *
-
-  Find files that don't contain #ifndef IGL_
-
-    grep -L "^#ifndef IGL_" *
-
-  Find .cpp files that contain ^using namespace
-
-    grep -l "^using namespace" *.cpp
-
-
-  Find .h files that contain ifndef IGL_*[^H]
-
-     grep -l "ifndef IGL_.*[^H] *$" *
+This is first and foremost a *header* library. Each header file should contain
+a single function.  The function may have multiple prototypes. All functions
+should use the igl namespace and should adhere to the conventions and styles
+listed below. 
 
+Further documentation is listed in tutorial.html, style_guidelines.html

scripts/doc.sh

@@ -1,27 +1,39 @@
 #!/bin/bash
 
+# THIS would be much easier with a ruby script that parsed each .h/.cpp pair
+# and created a <tr> row.
+#
+
 echo "<html>"
-echo "  <head><title>IGL LIB documentation</title></head>"
+echo "  <head>"
+echo "    <title>IGL LIB documentation</title>"
+echo '    <link href="./style.css" rel="stylesheet" type="text/css">'
+echo "  </head>"
 echo "  <body>"
 echo "    <h1>IGL LIB</h1>"
 echo "    <h2>Headers:</h2>"
 echo "    <table>"
 echo "      <tr><th>.h file</th><th>Functions</th></tr>"
 # loop over all headers
+odd="0"
 for h in include/igl/*.h;
 do
   b=`basename $h`
   if [ -e $h ]
   then
-    printf "      <tr id='$b'><td>$b</td>"
+    printf "      <tr id='$b' class=d$odd><td>$b</td>"
   fi
   # portion of file inside namespace 
-  html_nsp=`cat $h | perl -ne 'BEGIN{$p = 0;$\="<br>";} $o=$p;$p ^= $_=~"[{}]";print if $o && $p;'`
-  #html_nsp=`echo -e $nsp | sed -e "s/</\&lt;/g" | sed -e "s/>/\&gt;/g" | tr '\n' '<br>'`
-  #html_nsp=`echo -e $nsp | sed -e "s/</\&lt;/g" | sed -e "s/>/\&gt;/g" | sed -e "s/%/%%/g"`
+  html_nsp=`cat $h | \
+    perl -ne 'BEGIN{$p = 0} $o=$p;$p ^= $_=~"[{}]";print if $o && $p;' | \
+    sed -e "s/</\&lt;/g" | sed -e "s/>/\&gt;/g" | sed -e "s/%/%%/g" | \
+    sed -e "s/^\( *[^ \/].*\)$/<pre><code>\1<\/code><\/pre>/g" |  \
+    sed -e ':a' -e 'N' -e '$!ba' -e 's/<\/code><\/pre>\n<pre><code>/\\\n/g' | \
+    sed -e "s/^\(.*[^ ].*\)$/\1<br>/g"`;
   printf "<td>$html_nsp</td>"
   # Try to find functions and corresponding comments
   echo "</tr>"
+  odd=`echo "($odd+1)%2" | bc`
 done
 
 echo "  </body>"

style_guidelines.html

@@ -0,0 +1,190 @@
+<!DOCTYPE HTML>
+<html>
+  <head>
+    <title>IGL LIB - Style Guidelines</title>
+    <link href="./style.css" rel="stylesheet" type="text/css">
+  <body>
+    <img src=http://igl.ethz.ch/includes/images/logo-igl.gif alt="igl logo"
+    class=center>
+    <h1>igl_lib Style Guidelines</h1>
+    <p>
+This library is shared by many people. This document highlights some style
+guidelines for <i>developers</i> of the igl library.
+   </p>
+   <p>
+Each function prototype should be well documented.  Write a summary of what
+the function does and a description of each template, input and output in
+each prototype. 
+    </p>
+
+    <h2>Example</h2>
+    <p>
+Here is an example function defined in <code>include/igl/example_fun.h</code> and
+implemented in <code>include/igl/example_fun.cpp</code>.
+    </p>
+    <h3>example_fun.h</h3>
+    <pre><code>
+#ifndef IGL_EXAMPLE_FUN_H
+#define IGL_EXAMPLE_FUN_H
+
+#include "igl_inline.h"
+
+namespace igl
+{
+  // This is an example of a function, it takes a templated parameter and
+  // shovels it into cout
+  //
+  // Templates:
+  //   T  type that supports
+  // Input:
+  //   input  some input of a Printable type
+  // Returns true for the sake of returning something
+  template &lt;typename Printable&gt;
+  IGL_INLINE bool example_fun(const Printable & input);
+}
+
+#ifdef IGL_HEADER_ONLY
+#  include "example_fun.cpp"
+#endif
+
+#endif
+    </code></pre>
+    <h3>example_fun.cpp</h3>
+    <pre><code>
+#include "igl/example_fun.h"
+#include &lt;iostream&gt;
+
+template &lt;typename Printable&gt;
+IGL_INLINE bool igl::example_fun(const Printable & input)
+{
+  using namespace std;
+  cout&lt;&lt;"example_fun: "&lt;&lt;input&lt;&lt;endl;
+  return true;
+}
+
+#ifndef IGL_HEADER_ONLY
+template bool igl::example_fun&lt;double&gt;(const double& input);
+template bool igl::example_fun&lt;int&gt;(const int& input);
+#endif
+    </code></pre>
+
+
+
+    <h2>General rules</h2>
+    <ul>
+      <li> Use a single .h/.cpp pair with the same name as the function </li>
+      <li>
+At least one version of the function should use references for all outputs
+      </li>
+      <li>
+Functions with external dependencies should be a single .h file (no .cpp file)
+  so it won't appear in libigl.a
+      </li>
+      <li>
+Use wrappers and additional prototypes for returning single-output functions'
+outputs, but the default is to only use outputs
+      </li>
+      <li> All inputs should be const when appropriate </li>
+      <li>
+Use c++ references for inputs and outputs rather than pointers or pass-by-copy
+      </li>
+      <li>
+Take the time to write multiple prototypes if you'd like to have optional
+parameters with default values
+      </li>
+      <li>
+External dependencies (besides Eigen, OpenGL, etc.) are discouraged
+      </li>
+      <li>
+External dependencies must be clearly identified at the top of each file.
+      </li>
+      <li>
+External dependencies can go in the external/ directory
+      </li>
+      <li>
+Do not use the using namespace directive anywhere outside a local scope. This
+means never write: <code>using namespace std;</code> or <code>using namespace igl;</code> etc.
+      </li>
+      <li>
+Function names should either be the same as the corresponding MATLAB function
+or should use all lowercase separated by underscores: e.g.
+<code>my_function_name</code>
+      </li>
+      <li> Classes should be in <code>CamelCase</code></li>
+      <li> No tabs, only two spaces per indentation level </li>
+  </ul>
+
+    <h2>Specific rules</h2>
+    <p>
+Each file should be wrapped in an ifndef compiler directive. If the
+file's (and function's) name is example.h, then the ifndef should
+always begin with IGL_, then the function/file name in all caps then
+_H. As in:
+    </p>
+    <pre><code>
+#ifndef IGL_EXAMPLE_H
+#define IGL_EXAMPLE_H
+...
+#endif</code></pre>
+  
+    <p>
+Each file should begin with prototypes *without implementations* of
+each version of the function. All defined in the igl namespace. Each
+prototype should have its own comments describing what it is doing,
+and its templates, inputs, outputs.
+    </p>
+
+    <p>
+Implementation should be separated from prototypes in a .cpp file.
+    </p>
+
+    <p>
+Any includes, such as std libraries etc. should be in the .cpp file not the
+header .h file (whenever feasibly possible).
+    </p>
+
+    <p>
+Be generous by templating your inputs and outputs. If you do use
+templates, you must document the template just as you document inputs
+and outputs.
+    </p>
+
+    <h2>Useful scripts to check style</h2>
+  
+    <table>
+      <tr>
+        <th>script</th>
+        <th>Description</th>
+      <tr class=d0>
+        <td><code>grep -L inline *</code></td>
+        <td>Find files that aren't using "inline"</td>
+      </tr>
+      <tr class=d1>
+        <td><code>grep -L "namespace igl" *</code></td>
+        <td>Find files that aren't using igl namespace</td>
+      </tr>
+      <tr class=d0>
+        <td><code>grep -P '\t' *</code></td>
+        <td>Find files using [TAB] character</td>
+      </tr>
+      <tr class=d1>
+        <td><code>grep -L "^\/\/ Implementation" *</code></td>
+        <td>Find files that don't contain // Implementation</td>
+      </tr>
+      <tr class=d0>
+        <td><code>grep -L "^#ifndef IGL_" *</code></td>
+        <td>Find files that don't contain #ifndef IGL_</td>
+      </tr>
+      <tr class=d1>
+        <td><code>grep -l "^using namespace" *.cpp</code></td>
+        <td>Find .cpp files that contain ^using namespace</td>
+      </tr>
+      <tr class=d0>
+        <td><code>grep -l "ifndef IGL_.*[^H] *$" *</code></td>
+        <td>Find .h files that contain ifndef IGL_*[^H]</td>
+      </tr>
+    </table>
+
+    <p>See also: <a href=tutorial.html>tutorial</a></p>
+  </body>
+</html>

todos.txt

@@ -1,8 +1,12 @@
+- compile on Linux, Mac OS X, Windows
+- unit tests for all functions
+- standardize name of library: IGL LIB, igl_lib, igl lib, IGL Library, etc.
+- clean up examples
 - standardize use of string/char *, add to style conventions
 - standardize Eigen Templates, add to style conventions
-- standardize headers-only vs. static library
++ standardize headers-only vs. static library
 - clean up tga.h
-- standardize igl includes #include "cotangent.h" or #include <cotangent.h>
++ standardize igl includes #include "cotangent.h" or #include <cotangent.h>
 - implement an IGL_NO_OPENGL and IGL_NO_GLUT compiler option
 - clean up edgetopology.h
 - clean up mvc.h

tutorial.html

@@ -244,5 +244,6 @@ make
         href="matlab-to-eigen.html">Our own translation table</a> shows a list
         of common matlab functions and their igl-eigen equivalents.  
       </p>
+      <p>See also: <a href=style_guidelines.html>style guidlines</a></p>
   </body>
 </html>