Improved Doxygen documentation

- better code linking
- optional components

docs/Doxygen/doxyfile

@@ -679,13 +679,8 @@ INPUT                  = . \
                          ../../vcg/complex/algorithms/clean.h \
                          ../../vcg/complex/algorithms/refine.h \
                          ../../vcg/complex/algorithms/create/platonic.h \
-                         ../../vcg/complex/algorithms/geodesic.h
+                         ../../vcg/complex/algorithms/geodesic.h \
-                         ../../apps/sample/trimesh_base \
+                         ../../apps/sample/
-                         ../../apps/sample/trimesh_attribute \
-                         ../../apps/sample/trimesh_smooth \
-                         ../../apps/sample/trimesh_refine \
-                         ../../apps/sample/trimesh_inertia \
-                         ../../apps/sample/trimesh_sampling
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -711,7 +706,7 @@ FILE_PATTERNS          = *.cpp \
 # should be searched for input files as well. Possible values are YES and NO. 
 # If left blank NO is used.
 
-RECURSIVE              = NO
+RECURSIVE              = YES
 
 # The EXCLUDE tag can be used to specify files and/or directories that should be 
 # excluded from the INPUT source files. This way you can easily exclude a 
@@ -736,7 +731,7 @@ EXCLUDE_SYMLINKS       = NO
 # against the file with absolute path, so to exclude all test directories 
 # for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       = 
+EXCLUDE_PATTERNS       = moc_*
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names 
 # (namespaces, classes, functions, etc.) that should be excluded from the 
@@ -845,7 +840,7 @@ REFERENCES_RELATION    = NO
 # functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will 
 # link to the source code.  Otherwise they will link to the documentation.
 
-REFERENCES_LINK_SOURCE = YES
+REFERENCES_LINK_SOURCE = NO
 
 # If the USE_HTAGS tag is set to YES then the references to source code 
 # will point to the HTML generated by the htags(1) tool instead of doxygen 

docs/Doxygen/examples.dxy

@@ -4,7 +4,7 @@
 There are a number of very simple and short examples meant to document the various features of the library.
 
 trimesh_base.cpp
-
+trimesh_optional
 trimesh_attribute.cpp
 
 trimesh_normal.cpp

docs/Doxygen/index.dxy

@@ -29,6 +29,7 @@ Documentation
 Start from the following pages for basic concepts and examples.
 - \subpage install "Installing the VCG Library"
 - \subpage basic_concepts "Basic Concepts"
+- \subpage optional_component "Optional Component"
 - \subpage flags "Bit Flags on mesh elements"
 - \subpage adjacency "Adjacency and Topology"
 - \subpage allocation "Creating and destroying elements"

docs/Doxygen/optional_component.dxy

@@ -0,0 +1,49 @@
+/** \page optional_component
+Optional Component
+===
+There are many cases where some vertex or face attributes (like for example the Face-Face adjacency) are not necessary all the time.
+VCG Lib gives you a way to specify optional components, i.e. attributes that are not statically stored within the simplex but can be
+dynamically allocated only when you need them. Their use is totally transparent with respect to the standard, statically allocated components.
+
+To 'define' optional component you need to do two things:
+- to use a special type of container (derived from std::vector) in the mesh definition
+- to specify the right type of component in the simplex definition
+
+An optional component can be used only when it is 'enabled', e.g. when the memory for it has been allocated.
+An optional component can be enable by calling the function Enable.
+VCG Lib handles optional components with two alternative mechanisms: the first is called 'Ocf' (for Optional Component Fast)
+which uses one pointer for each simplex but it makes accessing optional attribute almost as fast as non-optional ones;
+the second is called 'Occ' (for Optional Component Compact) which only requires a little extra space for each mesh
+(unrelated to its size in terms of number of simplicies) but which can result in a slower access.
+In the following, only their use is discussed. The implementation detail can be found here.
+
+Optional Component Fast
+---
+The following definition of MyMesh specifies that a few components of the vertex and face types are optional.
+Note that  the special attribute vcg::vertex::InfoOcf and vcg::face::InfoOcf are the first attribute of vertex and face types and that we
+use the vcg::vertex::vector_ocf and vcg::face::vector_ocf as containers;
+
+\dontinclude trimesh_optional.cpp
+\skip MyVertexOcf
+\until MyMeshOcf
+
+
+Before accessing the data contained in the optional component you must enable that attribute by calling EnableXXX() corresponding function;
+afterwards the space for the component will be allocated and accessible until you call again DisableXXXX().
+
+\dontinclude trimesh_optional.cpp
+\skip cmof
+\until cmof
+\skip HasFFAdjacency
+\until true
+
+Trying to access the value of a unallocated component before enabling or after disabling the corresponding component
+will throw an assertion.
+
+\dontinclude trimesh_optional.cpp
+\skip EnableNormal
+\until UpdateNormal
+
+
+\sa trimesh_optional.cpp
+*/