[Cppunit-cvs] cppunit2/doc SConscript, 1.2, 1.3 coding_guidelines.dox, 1.1, 1.2

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/cppunit/cppunit2/doc
In directory sc8-pr-cvs4.sourceforge.net:/tmp/cvs-serv9695

Modified Files:
	SConscript coding_guidelines.dox 
Log Message:
- worked-around scons installation of doxygen without testing its existence.

Index: coding_guidelines.dox
===================================================================
RCS file: /cvsroot/cppunit/cppunit2/doc/coding_guidelines.dox,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** coding_guidelines.dox	7 Sep 2006 22:45:50 -0000	1.1
--- coding_guidelines.dox	14 Aug 2007 17:42:14 -0000	1.2
***************
*** 261,272 ****
  \section cg_guidelines Guidelines

- - config.h included in all headers (may be indirectly)
- - DLL macros
- - Forwards all classes and typedef in forwards.h
- - RAII
  - standard interfaces, but CppTL::ConstString as attribute to ensure thread-safety.
- - no member function template (use free function instead)
- - no cast style function template, use CppTL::Type instead (link issue with VC6)
  - use assertions to check precondition (or intermediate condition in complex algorithm)

! */
--- 261,403 ----
  \section cg_guidelines Guidelines

  - standard interfaces, but CppTL::ConstString as attribute to ensure thread-safety.
  - use assertions to check precondition (or intermediate condition in complex algorithm)

! \subsection cg_gl_headers Headers
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> All headers must either include the file <tt>config.</tt> of their library or include
! anything of the library (and therefore include the file <tt>config.</tt> indirectly).
! </DIV>
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> All classes and typedef must be exported using the <tt>XYZ_API</tt> macro, 
! where <tt>XYZ</tt> is the library macro prefix (see [\ref cg_macro]).
! </DIV>
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> All classes must be forward declared in <tt>forwards.h</tt> header of the library.
! </DIV>
! 
! \subsection cg_gl_using_namespace Using namespace directive
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> Never use the <tt>using namespace</tt> directive in any headers.
! </DIV>
! 
! Recommendation: Avoid the <tt>using namespace</tt> directive in any sources.
! 
! Rational: avoid poluting namespaces of sources including that header; enhance
! code readability by making obvious from which library a type/function originate from.
! 
! \subsection cg_gl_language_feature C++ language feature restrictions
! 
! \subsubsection cg_gl_nocastfn No cast style function template
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> All function template template argument must be deduced from
! parameters. Use CppTL::Type to explicitly pass the type as a parameter if needed.
! </DIV>
! 
! Rationale: some older compilers only includes function parameters type in the
! function signature used for link, resulting in very strange bug if cast style
! function templtes are used.
! 
! 
! Example:
! \code
! // usage: get<int>( value);
! template<class ValueType>
! CppTL::Any &get( const CppTL::Any &value );	// BAD
! 
! // usage: get(value,CppTL::Type<int>());
! template<class ValueType>
! CppTL::Any &get( const CppTL::Any &value, 
!                  CppTL::Type<ValueType> );	// OK
! \endcode
! 
! \subsubsection cg_gl_mtf Template member functions
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> Do not use template member functions (e.g. template methods).
! </DIV>
! 
! Template member functions should be avoided as they are not well supported by older
! compiler (e.g. VC++ 6.0). Usually, a template free functions can be used instead, taking
! as first parameter an instance of the class type.
! 
! Examples:
! \code
! class Any
! {
!    // Limited portability
!    template<class ValueType>	
!    void set( const ValueType &newValue );		// BAD
! };
! 
! // Most portable, use class any as first parameter
! template<class ValueType>
! CppTL::Any &set( CppTL::Any &value, const ValueType &newValue );	// OK
! \endcode
! 
! \subsection cg_gl_exception_safety Exception safety
! 
! We distinguish three levels of exception safety that a (member/free) function may provide:
! - No exception safety guaranty: the function might leak some resources, and leave the application in an undetermined state if an exception is thrown
! - Weak exception safety guaranty: the function will not leak any resources, but leave the application in an undetermined state
! - Strong exception safety guaranty: the function will not leak any resources, and the application will be in the same state as before the function call if an exception is thrown.
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> All code should provide at least the weak exception safety guaranty. 
! See [\ref cg_gl_raii] for tips on how to do that easily.
! </DIV>
! 
! Strongly recommended reading: Exceptional C++, by Herb Sutter. This book contains 
! very detailed examples explaining the some of the techniques exposed below (@todo). 
! Many of the articles of this book started their life in Guru of the Week columns:
! http://www.gotw.ca/gotw/.
! 
! 
! \subsection cg_gl_exception_spec Exception Specifications
! 
! Exception specification is the throw clause that specify the list of exception 
! of function may throw (see example below).
! 
! <DIV class='cg_rule'>
! <b>Rules:</b> Do not use throw specification unless required (subclassing std::exception for example).
! </DIV>
! 
! Rationale: Compilers dont deal as the one would expect in face of exception specification. 
! They often generate extra code and may disable inlining. 
! See boost guideline for detailed explanation: 
! http://www.boost.org/more/lib_guide.htm#Exception-specification.
! 
! Recommendation: Document exception thrown by functions with comment
! 
! Example:
! 
! \code
! double getValueAt( int index ) throw(IndexError); // BAD
! 
! // / \exception IndexError is raised if the provided index is invalid.
! double getValueAt( int index ); // GOOD
! \endcode
! 
! 
! \subsection cg_gl_raii Resource Acquisition Is Initialization principle (RAII)
! 
! The essence of this principle is simple:
! - acquire the resource in the constructor of a resource holder object
! - release the resource in the destructor of that same object
! 
! In the most simple case, resource is memory. A very common usage of this 
! principle is probably for locking/unlocking exclusive lock.
! 
! C++ guaranty that the destructor will always be called if the function returns or an
! exception is thrown. 
! 
! CppTL::ScopedPtr and CppTL::Mutex::ScopedLockGuard are examples of such objects.
! @todo
! 
! 
! */
\ No newline at end of file

Index: SConscript
===================================================================
RCS file: /cvsroot/cppunit/cppunit2/doc/SConscript,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** SConscript	16 Mar 2007 22:41:38 -0000	1.2
--- SConscript	14 Aug 2007 17:42:14 -0000	1.3
***************
*** 2,6 ****
  import os.path

! if 'doxygen' in env['TOOLS']:
      doc_topdir = env['ROOTBUILD_DIR']
      env['DOXYGEN_DOC_TOP_DIR'] = doc_topdir
--- 2,6 ----
  import os.path

! if env['HAS_DOXYGEN']:
      doc_topdir = env['ROOTBUILD_DIR']
      env['DOXYGEN_DOC_TOP_DIR'] = doc_topdir