cleaned things up a bit

.gitattributes

@@ -1766,6 +1766,9 @@ PDB.tmpout/todo -text
 PDB/demo/PDB/makefile -text
 PDB/demo/PDB/pdb_split.cpp -text
 PDB/demo/PDB/pdb_tree.cpp -text
+PDB/doc_doxygen/Doxyfile -text
+PDB/doc_doxygen/doc_footer -text
+PDB/doc_doxygen/main_doc -text
 PDB/dont_submit -text
 PDB/include/CGAL/PDB/Atom.h -text
 PDB/include/CGAL/PDB/Chain.h -text

PDB/doc_doxygen/Doxyfile

@@ -0,0 +1,240 @@
+# Doxyfile 1.5.1
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+PROJECT_NAME           = CGALPDB
+PROJECT_NUMBER         = 
+OUTPUT_DIRECTORY       = .
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+USE_WINDOWS_ENCODING   = NO
+BRIEF_MEMBER_DESC      = NO
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       = 
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = NO
+STRIP_FROM_PATH        = 
+STRIP_FROM_INC_PATH    = 
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+MULTILINE_CPP_IS_BRIEF = YES
+DETAILS_AT_TOP         = YES
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                = 
+OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_JAVA   = NO
+BUILTIN_STL_SUPPORT    = YES
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = NO
+EXTRACT_LOCAL_METHODS  = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = NO
+SHOW_DIRECTORIES       = NO
+FILE_VERSION_FILTER    = 
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = 
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = main_doc \
+                         ../include/CGAL/PDB \
+                         ../demo/PDB/
+FILE_PATTERNS          = *.h \
+                         *.cpp
+RECURSIVE              = YES
+EXCLUDE                = ../include/CGAL/PDB/internal \
+                         ../include/CGAL/PDB/macros.h
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = *_internal.h
+EXAMPLE_PATH           = ../demo/PDB/ \
+                         ../test/PDB/ \
+                         ../examples/PDB
+EXAMPLE_PATTERNS       = *.cpp
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             = 
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = doc_footer
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = YES
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = YES
+TREEVIEW_WIDTH         = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = ../../../fs/include
+INCLUDE_FILE_PATTERNS  = 
+PREDEFINED             = "CGAL_PDB_SUBSCRIPT(t,e)=t& operator[](unsigned int i); const t&operator[](unsigned int i);" \
+                         "CGAL_PDB_ITERATOR(uc,lc,it,b,e)=typedef it uc##_iterator; uc##_iterator lc##s_begin(); uc##_iterator lc##s_end();" \
+                         "CGAL_PDB_CONST_ITERATOR(uc,lc,it,b,e)=typedef it uc##_const_iterator; uc##_const_iterator begin() const; uc##_const_iterator end() const;" \
+                         "CGAL_PDB_SIZE(nm)=unsigned int number_of_##nm()const;" \
+                         "CGAL_PDB_INSERT(t,f)=t##_iterator insert(t##_key, const t&);" \
+                         "CGAL_PDB_FIND(uc,f)=uc##_iterator find(uc##_key); uc##_const_iterator find(uc##_key) const;" \
+                         "CGAL_PDB_RWFIELD(t,nm,v)=const t& nm() const; void set_##nm(const t&);" \
+                         CGAL_PDB_COPY_CONSTRUCTOR(t)= \
+                         "CGAL_PDB_SWAP(t)=inline void swap(t&, t&);" \
+                         "CGAL_PDB_OUTPUT(t)=/*!*/ inline std::ostream &operator<<(std::ostream&, const t&);"
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = NO
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = NO
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = YES
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = gif
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+MAX_DOT_GRAPH_WIDTH    = 1024
+MAX_DOT_GRAPH_HEIGHT   = 1024
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO

PDB/doc_doxygen/doc_footer

@@ -0,0 +1,2 @@
+    </BODY>
+  </HTML>

PDB/doc_doxygen/main_doc

@@ -0,0 +1,98 @@
+/*!
+	\mainpage A simple C++ PDB reader
+
+	\section i Introduction
+
+	This is a simple C++ PDB reader along with a couple of
+	 programs which use it to manipulate pdb files (applying a
+	 rigid transform or splitting/merging). The are aimed at
+	 people interested in proteins and RNA from a geometric
+viewpoint as
+	 they allow easy access to the geometry and bond structure in
+	 addition of the biological information. The library has two
+	 modes for reading/writing a pdb file. The simplest one,
+	 through the Chain class just reads and writes a single
+	 protein from/to a pdb file (which must have only one chain,
+	 but can have multiple models). The second, through the PDB
+	 class can handle pdb files with multiple models and herogens
+	 (although these are just passed through and not currently
+	 interpreted).
+
+	 Once a PDB is read, atom coordinates can be extracted,
+	 proteins can be aligned, and cRMS and dRMS can be computed, among
+	 other things.
+
+	The library is now tightly integrated with CGAL (http://www.cgal.org) and shipped as part of that library. 
+	 
+	\section struct Structure
+
+	Once a PDB file is read a PDB object is created. It
+	contains a number of Model objects corresponding to
+	each of the models in the PDB file. Each of these contains
+	several Chain objects once for each chain in the
+	Model.
+	 
+	\section progs Utility Programs
+
+	The library includes several utilities
+
+	- pdb_split which can split pdb files into separate models or
+          chains.
+
+	- pdb_tree which prints information about a PDB.
+
+	The programs use boost::program_options in order to handle
+	more complicated command line argument. The boost library can
+be found at http://www.boost.org
+	(and there are packages for most linux distributions).
+
+	\section ex Examples
+	
+	Examples for how to use the Chain and PDB
+	classes for reading and writing PDB files are detailed with
+	the respective classes. In addition, a program for splitting
+	one pdb containing several models into seperate pdb files is
+	included in the examples section.
+
+	
+	\section bugs Bugs/Issues
+
+	- Heterogens are not interpreted. They will be passed through
+          with each model just fine, but no data is extracted.
+
+	- Heterogens which are stored using ATOM records instead of
+          HETATM records cause errors.
+
+	\section Download
+
+	As me for the code drussel@salilab.org.
+
+	\section Changes
+	- 2.0 A rewrite which tied it in with CGAL and made it more iterator based. Many examples and demos were removed as they have not yet been updated. Most of the core functionality is much more cleanly accessible. 
+
+	- 1.0.4 Added structal like refinement of alignment of two
+              different proteins.
+	
+	- 1.0.3 Better handling of gaps in residue sequences and a
+              tool to strip sidechains from a pdb file.
+
+	- 1.0.2 Mostly just cleaned up the code. A bug fix with cRMS.
+	
+	- 1.0.1 Added arguments to control printing of error messages
+              when reading pdb files.
+
+	- 1.0 added support for computing cRMS and dRMS to
+            pdb_align. Some bug fixes.
+
+	- 0.9.7 added alignment and cRMS/dRMS code.
+
+	- 0.9.6 adds many consistency check allowing it to better
+              handle differences in atom naming schemes.
+
+	\section thanks Thanks
+
+	Thanks to Nikola for an earlier PDB reader from which I took the bond and atom data. 
+	The work was funded by a NSF graduate fellowship.
+	
+
+ */

PDB/dont_submit

@@ -1,3 +1,3 @@
 todo
 test/PDB/check_refine_alignment.cpp
-doc
+doc_doxygen

PDB/include/CGAL/PDB/Atom.h

@@ -70,7 +70,7 @@ public:
   //! Returns the van der Waals radius of the atom.
   /*!  Values take from the wikipedia so beware.
    */
-  inline double radius() const;
+  CGAL_PDB_ACCESSOR(double, radius, return radii_[type_]);
 
 
   //! This is a label which identifies an Atom uniquely within some scale.
@@ -126,25 +126,31 @@ inline int index_atoms(It b, It e, int start=0) {
 
 
 
-//! Take an atom label, atom pair and return the coordinates
+//! Take an Atom and return the Atom::point()
+/*!
+ */
 struct Point_from_atom {
   typedef Point result_type;
  
   const result_type& operator()(const Atom& a) const {
     return a.point();
   }
-  /*result_type& operator()(Atom& a) const {
-    return a.cartesian_coords();
-    }*/
 };
 
+//! Returns an interator which takes an Atom and return the coordinates
+/*!
+  The iterator value_type should be an Atom.
+
+ */
 template <class It>
 boost::transform_iterator<Point_from_atom, It>
 make_point_iterator(It it) {
   return boost::make_transform_iterator(it, Point_from_atom());
 }
 
-
+//! Take an Atom and return the Atom::index()
+/*!
+ */
 struct Index_from_atom {
   typedef Atom::Index result_type;
   
@@ -152,13 +158,20 @@ struct Index_from_atom {
     return a.index();
   }
 };
+//! Returns an interator which takes an Atom and return the Atom::index()
+/*!
+  The iterator value_type should be an Atom.
+
+ */
 template <class It>
 boost::transform_iterator<Index_from_atom, It>
 make_index_iterator(It it) {
   return boost::make_transform_iterator(it, Index_from_atom());
 }
 
-
+//! Take an Atom and return the a K::Weighted_point
+/*!
+ */
 template <class K>
 struct Weighted_point_from_atom {
   typedef typename K::Weighted_point result_type;
@@ -171,12 +184,19 @@ struct Weighted_point_from_atom {
   }
 };
 
+//! Return an interator which takes an Atom and return the a K::Weighted_point
+/*!
+  The iterator value_type should be an Atom.
+ */
 template <class It, class K>
 boost::transform_iterator<Weighted_point_from_atom<K>, It>
 make_weighted_point_iterator(It it, K k) {
   return boost::make_transform_iterator(it, Weighted_point_from_atom<K>());
 }
 
+//! Take an Atom and return the a K::Sphere_3
+/*!
+ */
 template <class K>
 struct Sphere_3_from_atom {
   typedef typename K::Sphere_3 result_type;
@@ -188,12 +208,17 @@ struct Sphere_3_from_atom {
 		       b.radius()*b.radius());
   }
 };
+//! Take an Atom and return the a K::Sphere_3
+/*!
+ */
 template <class It, class K>
 boost::transform_iterator<Sphere_3_from_atom<K>, It>
-make_weighted_point_iterator(It it, K k) {
+make_sphere_3_iterator(It it, K) {
   return boost::make_transform_iterator(it, Sphere_3_from_atom<K>());
 }
 
+
+//! Apply a transformation to the coordinates of an Atom
 class Transform_atom {
   Transform t_;
 public:

PDB/include/CGAL/PDB/Chain.h

@@ -33,9 +33,16 @@
 #include <CGAL/PDB/internal/dummies.h>
 #include <CGAL/PDB/internal/Nested_iterator.h>
 #include <boost/tuple/tuple.hpp>
+#include <CGAL/PDB/macros.h>
 
 CGAL_PDB_BEGIN_NAMESPACE
 
+/*!
+  \file Chain.h 
+
+  This file contains the class Chain.
+*/
+
 class Model;
   
 //! A class representing a single chain of a protein.  
@@ -66,12 +73,6 @@ public:
 
   typedef small_map<Monomer_iterator_value_type> Container;
   
- 
-  /*!
-    \example check_protein.cpp
-  */
-
-  
   /*! Build a protein from a pdb file.
     See check_protein.cpp for an example of using this to read a
     pdb file.
@@ -95,21 +96,23 @@ public:
 
 
   //! A unique identified of an atom in the chain
-  struct Atom_key: public std::pair<Monomer_key, Monomer::Atom_key>{
+  class Atom_key {
-    typedef std::pair<Monomer_key, Monomer::Atom_key> P;
+    Monomer_key mk_;
-    Atom_key(Monomer_key mk, Monomer::Atom_key at): P(mk, at){}
+    Monomer::Atom_key ak_;
+   public:
+    Atom_key(Monomer_key mk, Monomer::Atom_key ak): mk_(mk), ak_(ak){}
     Atom_key(){}
     operator Monomer::Atom_key() const {
-      return P::second;
+      return ak_;
     }
     operator Monomer_key() const {
-      return P::first;
+      return mk_;
     }
     Monomer::Atom_key atom_key() const {
-      return P::second;
+      return ak_;
     }
     Monomer_key monomer_key() const {
-      return P::first;
+      return mk_;
     }
   };
 
@@ -131,21 +134,34 @@ public:
 
   CGAL_PDB_INSERT(Monomer,  return insert_internal(k,m));
 
+  class Atom_iterator_value_type {
+      Atom_key index_;
+      Atom *atom_;
+    public:
+      Atom_iterator_value_type(Atom_key f, Atom* s): index_(f), atom_(s){}
+      Atom_key key() const {return index_;}
+      Atom &atom() const {return *atom_;}
+      Atom_iterator_value_type():atom_(NULL){}
+    };
 
-protected:
+  class Atom_const_iterator_value_type {
+    Atom_key index_;
+    const Atom *atom_;
+  public:
+    Atom_const_iterator_value_type(Atom_key f, const Atom* s): index_(f), atom_(s){}
+    Atom_key key() const {return index_;}
+    const Atom &atom() const {return *atom_;}
+    Atom_const_iterator_value_type():atom_(NULL){}
+  };
+private:
+
+  //! \cond
   Monomer_iterator insert_internal(Monomer_key k, const Monomer &m);
 
   struct Iterator_traits {
     typedef Monomer_iterator Outer_it;
     typedef Monomer::Atom_iterator Inner_it;
-    struct value_type {
+    typedef Atom_iterator_value_type value_type;
-      Atom_key index_;
-      Atom *atom_;
-      value_type(Atom_key f, Atom* s): index_(f), atom_(s){}
-      Atom_key key() const {return index_;}
-      Atom &atom() const {return *atom_;}
-      value_type():atom_(NULL){}
-    };
     struct Inner_range{
       std::pair<Inner_it, Inner_it> operator()(Outer_it it) const {
 	return std::make_pair(it->monomer().atoms_begin(), it->monomer().atoms_end());
@@ -162,14 +178,7 @@ protected:
   struct Iterator_const_traits {
     typedef Monomer_const_iterator Outer_it;
     typedef Monomer::Atom_const_iterator Inner_it;
-    struct value_type {
+    typedef Atom_const_iterator_value_type value_type;
-      Atom_key index_;
-      const Atom *atom_;
-      value_type(Atom_key f, const Atom* s): index_(f), atom_(s){}
-      Atom_key key() const {return index_;}
-      const Atom &atom() const {return *atom_;}
-      value_type():atom_(NULL){}
-    };
     struct Inner_range{
       boost::tuple<Inner_it, Inner_it> operator()(Outer_it it) const {
 	return boost::make_tuple(it->monomer().atoms_begin(), it->monomer().atoms_end());
@@ -181,9 +190,9 @@ protected:
       }
     };
   };
+  //! \endcond
 public:
   
-  void swap_with(Chain &o);
   
   //! An iterator to iterate through all the atoms of the protein  
   CGAL_PDB_ITERATOR(Atom, atom, 
@@ -200,11 +209,12 @@ public:
   //! This is non-const time.
   unsigned int number_of_atoms() const;
 
-  //! An iterator through the bonds of a CGAL::PDB::Chain
+  //! \cond
+  void swap_with(Chain &o);
+
   class Bond_it {
     friend class Chain;
   public:
-    //! The value_type is a CGAL::PDB::Chain::Bond
     typedef Bond value_type;
     typedef std::forward_iterator_tag iterator_category;
     typedef std::size_t difference_type;
@@ -257,7 +267,7 @@ public:
     CGAL_PDB_COPY_CONSTRUCTOR(Bond_it);
 
   
-  protected:
+  private:
     void copy_from(const Bond_it &o) {
       rit_= o.rit_;
       rend_= o.rend_;
@@ -297,7 +307,7 @@ public:
     bool between_;
     Bond ret_;
   };
-
+  //! \endcond
 
   CGAL_PDB_CONST_ITERATOR(Bond, bond, Bond_it,
 			  return Bond_const_iterator(residues_.begin(), residues_.end()),
@@ -350,7 +360,7 @@ public:
   void set_has_bonds(bool tf);
 
   CGAL_PDB_RWFIELD(std::string, name, name_);
-protected:
+private:
   void process_line(const char *line);
     
   //unsigned int residue_offset_of_atom_key(Atom::Index i) const;

PDB/include/CGAL/PDB/Model.h

@@ -74,6 +74,7 @@ public:
 
   CGAL_PDB_SIZE(chains, return chains_.size());
 
+  //! \cond
   class Hetatom_data {
   public:
     Hetatom_data(const char *rnm, 
@@ -117,10 +118,13 @@ public:
     Chain_key chain_;
       
   };
+  //! \endcond
+
 
   CGAL_SMALL_MAP_VALUE_TYPE(Hetatom_vt, Hetatom_data, Atom, atom);
-
+  //! \cond
   typedef std::vector<Hetatom_vt > Hetatoms;
+  //! \endcond
 
   //! An iterator through CGAL::PDB::Atom values for the HETATM records.
   CGAL_PDB_CONST_ITERATOR(Hetatom, hetatom, 
@@ -180,20 +184,30 @@ public:
 
   //! A chemical bond within the protein
   typedef std::pair<Bond_endpoint, Bond_endpoint> Bond; 
-
+  class Atom_iterator_value_type {
+      Atom_key index_;
+      Atom *atom_;
+  public:
+      Atom_iterator_value_type(Atom_key f, Atom* s): index_(f), atom_(s){}
+      Atom_key key() const {return index_;}
+      Atom &atom() const {return *atom_;}
+      Atom_iterator_value_type():atom_(NULL){}
+    };
+  class Atom_const_iterator_value_type {
+      Atom_key index_;
+      const Atom *atom_;
+  public:
+      Atom_const_iterator_value_type(Atom_key f, const Atom* s): index_(f), atom_(s){}
+      Atom_key key() const {return index_;}
+      const Atom &atom() const {return *atom_;}
+      Atom_const_iterator_value_type():atom_(NULL){}
+    };
 protected:
-
+  //! \cond
  struct Iterator_traits {
     typedef Chain_iterator Outer_it;
     typedef Chain::Atom_iterator Inner_it;
-    struct value_type {
+   typedef Atom_iterator_value_type value_type;
-      Atom_key index_;
-      Atom *atom_;
-      value_type(Atom_key f, Atom* s): index_(f), atom_(s){}
-      Atom_key key() const {return index_;}
-      Atom &atom() const {return *atom_;}
-      value_type():atom_(NULL){}
-    };
     struct Inner_range{
       std::pair<Inner_it, Inner_it> operator()(Outer_it it) const {
 	return std::make_pair(it->chain().atoms_begin(), it->chain().atoms_end());
@@ -211,14 +225,7 @@ protected:
   struct Iterator_const_traits {
     typedef Chain_const_iterator Outer_it;
     typedef Chain::Atom_const_iterator Inner_it;
-    struct value_type {
+    typedef Atom_const_iterator_value_type value_type;
-      Atom_key index_;
-      const Atom *atom_;
-      value_type(Atom_key f, const Atom* s): index_(f), atom_(s){}
-      Atom_key key() const {return index_;}
-      const Atom &atom() const {return *atom_;}
-      value_type():atom_(NULL){}
-    };
    struct Inner_range{
       std::pair<Inner_it, Inner_it> operator()(Outer_it it) const {
 	return std::make_pair(it->chain().atoms_begin(), it->chain().atoms_end());
@@ -231,7 +238,7 @@ protected:
       }
     };
   };
-
+  //! \endcond
 public:
  //! An iterator to iterate through all the atoms of the protein  
   CGAL_PDB_ITERATOR(Atom, atom, 
@@ -245,7 +252,7 @@ public:
 		    return Atom_const_iterator(chains_.end(), chains_.end()));
 
 
- //! An iterator through the bonds of a CGAL::PDB::Chain
+  //! \cond
   class Bond_it {
     friend class Model;
   public:
@@ -321,7 +328,7 @@ public:
     Chain::Bond_const_iterator ait_;
     Bond ret_;
   };
-
+  //! \endcond
 
   CGAL_PDB_CONST_ITERATOR(Bond, bond, Bond_it,
 			  return Bond_const_iterator(chains_.begin(),
@@ -330,7 +337,7 @@ public:
 						     chains_.end()));
  
 
-protected:
+private:
   void process_line(const char *c);
 
   std::vector<std::string> extra_;

PDB/include/CGAL/PDB/PDB.h

@@ -85,7 +85,7 @@ public:
   };
 
 
- //! An iterator through the unparsed std::string lines of the header of the PDB.
+  //! An iterator through the unparsed std::string lines of the header of the PDB.
   CGAL_PDB_CONST_ITERATOR(Header, header, 
 		      std::vector<std::string>::const_iterator,
 		      return header_.begin(),
@@ -100,26 +100,38 @@ public:
   CGAL_PDB_CONST_ITERATOR(Model, model, Models::const_iterator, 
 		return models_.begin(),
 		return models_.end());
+
   //! Find a Model with the given key, return models_end() if none is found
   CGAL_PDB_FIND(Model, return models_.find(k));
 
- //! Add a model (or change an existing one).
+  //! Add a model (or change an existing one).
   CGAL_PDB_INSERT(Model, return models_.insert(Models::value_type(k,m)));
 
-protected:
 
-  struct Iterator_traits {
+  class Chain_iterator_value_type {
-    typedef Model_iterator Outer_it;
-    typedef Model::Chain_iterator Inner_it;
-    class value_type {
       Chain_key index_;
       Chain *chain_;
     public:
-      value_type(Chain_key f, Chain* s): index_(f), chain_(s){}
+      Chain_iterator_value_type(Chain_key f, Chain* s): index_(f), chain_(s){}
       Chain_key key() const {return index_;}
       Chain &chain() const {return *chain_;}
-      value_type():chain_(NULL){}
+      Chain_iterator_value_type():chain_(NULL){}
     };
+  class Chain_const_iterator_value_type {
+      Chain_key index_;
+      const Chain *chain_;
+    public:
+      Chain_const_iterator_value_type(Chain_key f, const Chain* s): index_(f), chain_(s){}
+      Chain_key key() const {return index_;}
+      const Chain &chain() const {return *chain_;}
+      Chain_const_iterator_value_type():chain_(NULL){}
+    };
+protected:
+  //! \cond
+  struct Iterator_traits {
+    typedef Model_iterator Outer_it;
+    typedef Model::Chain_iterator Inner_it;
+    typedef Chain_iterator_value_type value_type;
     struct Inner_range{
       std::pair<Inner_it, Inner_it> operator()(Outer_it it) const {
 	return std::make_pair(it->model().chains_begin(), it->model().chains_end());
@@ -136,15 +148,7 @@ protected:
   struct Iterator_const_traits {
     typedef Model_const_iterator Outer_it;
     typedef Model::Chain_const_iterator Inner_it;
-     class value_type {
+    typedef Chain_const_iterator_value_type value_type;
-      Chain_key index_;
-      const Chain *chain_;
-    public:
-      value_type(Chain_key f, const Chain* s): index_(f), chain_(s){}
-      Chain_key key() const {return index_;}
-      const Chain &chain() const {return *chain_;}
-      value_type():chain_(NULL){}
-    };
     struct Inner_range{
       std::pair<Inner_it, Inner_it> operator()(Outer_it it) const {
 	return std::make_pair(it->model().chains_begin(), it->model().chains_end());
@@ -156,7 +160,7 @@ protected:
       }
     };
   };
- 
+  //! \endcond
 public:
  
   //! An iterator through the CGAL::PDB::Chain objects contained in the PDB.
@@ -174,7 +178,7 @@ public:
 
  
 
-protected:
+private:
   void load(std::istream &in, bool print_errors);
 
   std::vector<std::string> header_;

PDB/include/CGAL/PDB/Point.h

@@ -30,21 +30,21 @@ CGAL_PDB_BEGIN_NAMESPACE
 
   typedef CGAL::Exact_predicates_inexact_constructions_kernel::Point_3 Point;
   typedef CGAL::Exact_predicates_inexact_constructions_kernel::Vector_3 Vector;
-
+//! \cond
   struct Squared_distance{
     double operator()(const Point &a, const Point &b) const {
       return CGAL::squared_distance(a,b);
     }
   };
 
-  //! Functor to compute the squared norm of a Vector
+
   struct Squared_norm{
     double operator()(const Vector &v) const {
       return v.x()*v.x()+v.y()*v.y()+ v.z()*v.z();
     }
   };
 
-  //! Functor to compute the cross product of two vectors
+ 
   struct Cross_product{
     Vector operator()(const Vector &a, const Vector &b) const {
       double x = a.y() * b.z() - b.y() * a.z();
@@ -55,18 +55,16 @@ CGAL_PDB_BEGIN_NAMESPACE
     }
   };
 
-  /*!
+ 
-    This class represents a point in spherical coordinates. 
-  */
   struct Spherical_point{
-    //! Construct a spherical point from coordinates.
+    // Construct a spherical point from coordinates.
     Spherical_point(double r, double theta, double phi) {
       phi_=phi;
       theta_=theta;
       r_=r;
     }
 
-    //! Construct a point from a vector.
+    // Construct a point from a vector.
     Spherical_point(const Vector &v) {
       double xy2=v.x()*v.x()+v.y()*v.y();
       double sd= std::sqrt(xy2+v.z()*v.z());
@@ -100,8 +98,8 @@ CGAL_PDB_BEGIN_NAMESPACE
   };
 
 
-  //! Construct a spherical point with a certain axis.
+  // Construct a spherical point with a certain axis.
-  /*!  \note This class is poorly designed having two completely
+  /*  \note This class is poorly designed having two completely
     separate usages just sharing internal code.
   */
   struct Construct_spherical_point{
@@ -118,7 +116,7 @@ CGAL_PDB_BEGIN_NAMESPACE
       make_axis(p-pop, popop-pop);
     }
     
-    //! Construct the spherical coordinates of a vector.
+    // Construct the spherical coordinates of a vector.
     Spherical_point operator()(const Vector &v) const {
       double vz= v*z_;
       double vx= v*x_;
@@ -126,7 +124,7 @@ CGAL_PDB_BEGIN_NAMESPACE
       return Spherical_point(vx, vy, vz);
     };
 
-    //! Construct the spherical coordinates of a point relative to the base passed in the constructor.
+    // Construct the spherical coordinates of a point relative to the base passed in the constructor.
     Spherical_point operator()(const Point &p) const {
       return operator()(p-base_);
     }
@@ -148,5 +146,6 @@ CGAL_PDB_BEGIN_NAMESPACE
     Point base_;
   };
   
+//! \endcond
 CGAL_PDB_END_NAMESPACE
 #endif

PDB/include/CGAL/PDB/Quaternion.h

@@ -7,8 +7,7 @@
 #include <iostream>
 
 CGAL_PDB_BEGIN_NAMESPACE
-
+//! \cond
-//! A trivial class for representing quaternions
 class Quaternion {
 protected:
   typedef double NT;
@@ -82,5 +81,6 @@ inline std::ostream &operator<<(std::ostream &out, const Quaternion &q) {
   return out;
 }
 
+//! \endcond
 CGAL_PDB_END_NAMESPACE
 #endif

PDB/include/CGAL/PDB/Transform.h

@@ -8,109 +8,7 @@
 CGAL_PDB_BEGIN_NAMESPACE
 
 typedef Aff_transformation_3<CGAL::Exact_predicates_inexact_constructions_kernel> Transform;
-#if 0
-  //! This class provides a simple rigid transformation matrix
-  /*!  The matrix has a rotational an a translational part. However,
-    it is not enforced that the rotational part is actually just a
-    rotation (this is slightly tricky due to possible numeric errors.
-  */
-  struct Transform {
-    typedef double NT;
-    Transform(){
-      for (unsigned int i=0; i< 3; ++i){
-	rot_[i][0]=0;
-	rot_[i][1]=0;
-	rot_[i][2]=0;
-	rot_[i][i]=1;
-	trans_[i]=0;
-      }
-    }
 
-    //! Construct a transform from a rotation matrix and an offset vector.
-    template <class TA, class TB>
-    Transform(TA rot, TB trans){
-      for (unsigned int i=0; i< 3; ++i){
-	trans_[i]=trans[i];
-	for (unsigned int j=0; j< 3; ++j){
-	  rot_[i][j]=rot[i][j];
-	}
-      }
-      
-#ifndef NDEBUG
-      NT m01 = rot[0][0]*rot[1][1] - rot[1][0]*rot[0][1];
-      NT m02 = rot[0][0]*rot[2][1] - rot[2][0]*rot[0][1];
-      NT m12 = rot[1][0]*rot[2][1] - rot[2][0]*rot[1][1];
-      NT det = m01*rot[2][2] - m02*rot[1][2] + m12*rot[0][2];
-      assert(det >0);
-      assert(std::abs(1-det) < .25);
-#endif
-    }
-
-    Transform(const Vector &trans, const Quaternion &q);
-
-
-    //! Apply a transformation to a point
-    template <class Point>
-    Point operator()(const Point &pt) const {
-      NT ix= pt.x();// + trans_[0];
-      NT iy= pt.y();// + trans_[1];
-      NT iz= pt.z();// + trans_[2];
-      NT x= ix*rot_[0][0] + iy*rot_[0][1] + iz*rot_[0][2] + trans_[0];
-      NT y= ix*rot_[1][0] + iy*rot_[1][1] + iz*rot_[1][2] + trans_[1];
-      NT z= ix*rot_[2][0] + iy*rot_[2][1] + iz*rot_[2][2] + trans_[2];
-      return Point(x,y,z);
-    }
-
-
-
-    //! Set the translation part of the transformation matrix.
-    template <class Pt>
-    void set_translation(Pt tr){
-      trans_[0]=tr.x();
-      trans_[1]=tr.y();
-      trans_[2]=tr.z();
-    }
-    
-    const NT* translation() const {
-      return trans_;
-    }
-
-    Quaternion quaternion() const {
-      return Quaternion(rot_);
-    }
-
-    void write(std::ostream &out) const;
-
-    NT error(const Transform &o) const {
-      NT n=0;
-      for (unsigned int i=0; i< 3; ++i){
-	n += std::abs(o.trans_[i]- trans_[i]);
-	for (unsigned int j=0; j< 3; ++j){
-	  n+= std::abs(o.rot_[i][j]- rot_[i][j]);
-	}
-      }
-      return n;
-    }
-
-  private:
-    NT rot_[3][3];
-    NT trans_[3];
-  };
-  
-  //! Write the transformation matrix to a stream.
-  /*!
-    The output format is 
-    r r r t
-    r r r t
-    r r r t
-    0 0 0 1
-  */
-  inline std::ostream &operator<<(std::ostream &out, const Transform &t) {
-    t.write(out);
-    return out;
-  }
-
-#endif
 CGAL_PDB_END_NAMESPACE
 
 #endif

PDB/include/CGAL/PDB/align.h

@@ -7,7 +7,7 @@
 
 CGAL_PDB_BEGIN_NAMESPACE
 
-
+//! \cond
 inline double structal_score(const CGAL_PDB_NS::Point& a, 
 			     const CGAL_PDB_NS::Point& b) {
   CGAL_PDB_NS::Squared_distance sd;
@@ -28,6 +28,7 @@ struct DpP {
 inline std::ostream &operator<<(std::ostream &o, DpP p){
   return o << "(" << p.first << " " << p.second << ")";
 }
+//! \endcond
 
 
 /*!  This computes the optimal rigid transform minimizing the least

PDB/include/CGAL/PDB/iterator.h

@@ -49,7 +49,7 @@ boost::transform_iterator<Get_atom, It> make_atom_iterator(It it){
 
 
 struct Get_bond_indices {
-  typedef std::pair<int,int> result_type;
+  typedef std::pair<unsigned int,unsigned int> result_type;
   template <class B>
   const result_type& operator()(const B & b) const {
     static result_type ret;
@@ -150,5 +150,9 @@ make_ok_bond_iterator( OKA oka, It itb, It ite){
 
 
 
+/*! \example extracting_geometry.cpp
+  This example shows how to use the various iterator adaptors for extracting geometry and connectivity.
+ */
+
 CGAL_PDB_END_NAMESPACE
 #endif

PDB/src/CGALPDB/Atom.cpp

@@ -47,4 +47,5 @@ Atom::Type Atom::string_to_type(const char *cp) {
     return INVALID;
   }
 }
+
 CGAL_PDB_END_NAMESPACE