Author: mlandres Date: Thu Oct 2 17:23:14 2008 New Revision: 11232 URL: http://svn.opensuse.org/viewcvs/zypp?rev=11232&view=rev Log: - Removed doxygen files from source tree. Additional documentation and related pages are now located in doc/autoinclude. Added: trunk/libzypp/doc/autoinclude/ trunk/libzypp/doc/autoinclude/CodeSnippets.doc trunk/libzypp/doc/autoinclude/Mainpage.doc trunk/libzypp/doc/autoinclude/README trunk/libzypp/doc/autoinclude/Testcases.doc trunk/libzypp/doc/autoinclude/g_BOOST.doc trunk/libzypp/doc/autoinclude/g_SATSOLVER.doc trunk/libzypp/doc/autoinclude/groups.doc trunk/libzypp/doc/autoinclude/notes/ trunk/libzypp/doc/autoinclude/notes/n_ResPool_nomorenameiter Removed: trunk/libzypp/zypp/@DOXYGEN/ Modified: trunk/libzypp/doc/autodoc/CMakeLists.txt trunk/libzypp/doc/autodoc/Doxyfile.cmake Modified: trunk/libzypp/doc/autodoc/CMakeLists.txt URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autodoc/CMakeLists.txt?rev=11232&r1=11231&r2=11232&view=diff ============================================================================== --- trunk/libzypp/doc/autodoc/CMakeLists.txt (original) +++ trunk/libzypp/doc/autodoc/CMakeLists.txt Thu Oct 2 17:23:14 2008 @@ -8,8 +8,9 @@ SET( HAVE_DOT YES ) ENDIF ( NOT DOT ) -SET( ZYPP_SOURCE_DIR ${CMAKE_SOURCE_DIR}/zypp ) -SET( ZYPP_EXAMPLE_DIR ${CMAKE_SOURCE_DIR}/zypp/@DOXYGEN ) +SET( ZYPP_SOURCE_DIR ${CMAKE_SOURCE_DIR}/zypp ) +SET( ZYPP_DOCINCLUDE_DIR ${CMAKE_SOURCE_DIR}/doc/autoinclude ) +SET( ZYPP_EXAMPLE_DIR ${CMAKE_SOURCE_DIR}/examples ) SET( DOXYGEN_INPUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile ) SET( DOXYGEN_OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/index.html ) Modified: trunk/libzypp/doc/autodoc/Doxyfile.cmake URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autodoc/Doxyfile.cmake?rev=11232&r1=11231&r2=11232&view=diff ============================================================================== --- trunk/libzypp/doc/autodoc/Doxyfile.cmake (original) +++ trunk/libzypp/doc/autodoc/Doxyfile.cmake Thu Oct 2 17:23:14 2008 @@ -8,7 +8,6 @@ OUTPUT_DIRECTORY = CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English -USE_WINDOWS_ENCODING = NO BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES ABBREVIATE_BRIEF = @@ -71,13 +70,13 @@ #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = @ZYPP_SOURCE_DIR@ -FILE_PATTERNS = +INPUT = @ZYPP_DOCINCLUDE_DIR@ @ZYPP_SOURCE_DIR@ +FILE_PATTERNS = *.h *.hh *.hxx *.hpp *.h++ *.c *.cc *.cxx *.cpp *.c++ *.tcc *.hcc *.doc RECURSIVE = YES EXCLUDE = EXCLUDE_SYMLINKS = NO EXCLUDE_PATTERNS = -EXAMPLE_PATH = @ZYPP_EXAMPLE_DIR@ +EXAMPLE_PATH = @ZYPP_DOCINCLUDE_DIR@ @ZYPP_EXAMPLE_DIR@ EXAMPLE_PATTERNS = EXAMPLE_RECURSIVE = NO IMAGE_PATH = @@ -209,8 +208,6 @@ DOT_IMAGE_FORMAT = png 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 Added: trunk/libzypp/doc/autoinclude/CodeSnippets.doc URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/CodeSnippets.doc?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/CodeSnippets.doc (added) +++ trunk/libzypp/doc/autoinclude/CodeSnippets.doc Thu Oct 2 17:23:14 2008 @@ -0,0 +1,122 @@ +/** \page CodeSnippets Code Snippets + +\section for_ + If you prefer using iterator in a \c for loop, but dislike to figure out + the exact type of the iterator, you may find the \c for_ macro convenient: + \code + #include "zypp/base/Easy.h" + + for_( it, pool.byIdentBegin( kind, name ), + pool.byIdentEnd( kind, name ) ) + { + PoolItem copy = *it; + } + \endcode + instead of: + \code + for ( ResPool::byIdent_iterator it = pool.byIdentBegin( kind, name ), + end = pool.byIdentEnd( kind, name ); + it != end, ++it ) + { + PoolItem copy = *it; + } + \endcode + +\section erase erase elements from containers + \verbatim + // ////////////////////////////////////////////////////////////////////// + // Avoid buggy code, that tries to erase elements, matching a + // certain property from containers. Example: + // + // for (ResStore::iterator it = store.begin(); it != store.end(); ++it) + // { + // _pool.erase(*it); + // } + // + // Problem: Removing an element from a container invalidates (at least) + // all iterators pointing to it. Thus after erasing *it, it is + // no longer valid. ++it has UNDEFINED BEHAVIOUR. + + // ////////////////////////////////////////////////////////////////////// + // Loop based algorithms (differs depending on the kind of container) + // ===================== + // ////////////////////////////////////////////////////////////////////// + + // ////////////////////////////////////////////////////////////////////// + // Sequential container (vector string deque list): erase returns + // a valid iterator to the next element. + // ////////////////////////////////////////////////////////////////////// + + SeqContainer c; + for ( SeqContainer::iterator it = c.begin(); it != c.end(); /**/ ) + { + if ( toBeRemoved( *it ) ) + { + it = c.erase( it ); // valid next-iterator returned + } + else + ++it; + } + + + // ////////////////////////////////////////////////////////////////////// + // Associative container (maps sets): erase returns void, but we can use + // postfix increment, as ONLY iterators to the eased object get invalid: + // ////////////////////////////////////////////////////////////////////// + + AssocContainer c; + for ( AssocContainer::iterator it = c.begin(); it != c.end(); /**/ ) + { + if ( toBeRemoved( *it ) ) + { + c.erase( it++ ); // postfix! Incrementing before erase + } + else + ++it; + } + + + // ////////////////////////////////////////////////////////////////////// + // stl algorithms + // ============== + // + // In case toBeRemoved above is actually a function/functor. + // ////////////////////////////////////////////////////////////////////// + + + // ////////////////////////////////////////////////////////////////////// + // Sequential container (vector string deque): stl::remove_if, + // does not erase elements, they are just moved to the containers + // end, and an iterator to the 1st item to be 'removed' is returned. + // ////////////////////////////////////////////////////////////////////// + + SeqContainer c; + c.erase( stl::remove_if( c.begin(), c.end(), toBeRemoved ), + c.end() ); + + + // ////////////////////////////////////////////////////////////////////// + // Sequential container (list): The above works too, but list has a + // builtin remove/remove_if which is more efficient. + // ////////////////////////////////////////////////////////////////////// + + list c; + c.remove_if( toBeRemoved ); + + + // ////////////////////////////////////////////////////////////////////// + // Associative container (maps sets): Actually the loop above is the most + // efficient solution. There is an algorithm based solution, but it requires + // copying all elements not to be removed ;( + // ////////////////////////////////////////////////////////////////////// + + AssocContainer c; + + AssocContainer keepItems; + stl::remove_copy_if( c.begin(), c.end(), + stl::inserter( keepItems, keepItems.end() ), + toBeRemoved ); + c.swap( keepItems ); + \endverbatim + +*/ \ No newline at end of file Added: trunk/libzypp/doc/autoinclude/Mainpage.doc URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/Mainpage.doc?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/Mainpage.doc (added) +++ trunk/libzypp/doc/autoinclude/Mainpage.doc Thu Oct 2 17:23:14 2008 @@ -0,0 +1,6 @@ +/** \namespace zypp libzypp +*/ +** \mainpage Welcome to libzypp + + +*/ \ No newline at end of file Added: trunk/libzypp/doc/autoinclude/README URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/README?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/README (added) +++ trunk/libzypp/doc/autoinclude/README Thu Oct 2 17:23:14 2008 @@ -0,0 +1,54 @@ +All .doc files here will be parsed and included in the autodocs generated +by doxygen (see http://www.doxygen.org/). All the other files here (mostly +below notes) are available to be vervatim included in some documentation +block using: + + /** \include somefile + */ + or + /** \example + */ + + +The .doc files here will mostly provide: + +- The content of the main index page (defined in Mainpage.doc). + +- Other related documentation pages: + + /*! \page page1 A documentation page + Leading text. + \section sec An example section + This page contains the subsections \ref subsection1 and \ref subsection2. + For more info see page \ref page2. + \subsection subsection1 The first subsection + Text. + \subsection subsection2 The second subsection + More text. + */ + + /*! \page page2 Another page + Even more info. + */ + +Those pages will per default appear in the documentations 'Related Pages' +section, unless you refer to them from within soome other page by using +'\subpage': + + /** \mainpage A simple manual + + Some general info. + + This manual is divided in the following sections: + - \subpage intro + - \subpage advanced "Advanced usage" + */ + + +- Documentation for a group of classes defined by \ingroup: + + /*! \defgroup g_Resolvable Resolvable Objects + Some explanation. + */ + +- And whatever else we don't want to keep in the header files. Added: trunk/libzypp/doc/autoinclude/Testcases.doc URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/Testcases.doc?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/Testcases.doc (added) +++ trunk/libzypp/doc/autoinclude/Testcases.doc Thu Oct 2 17:23:14 2008 @@ -0,0 +1,39 @@ +/** \page Testcases Writing Testcases + +\verbatim + - added tests/data/openSUSE-11.1 containing raw susetags metadata. + Keeping .solv files in svn is somewhat inconvenient, as you must rebuild them + if something in satsolver changes. +\endverbatim + +\verbatim + - added tests/include as location for includes that might be used in multiple + testcases. +\endverbatim + +\verbatim + - added tests/include/TestSetup.h to ease building a test environment below + some tempdir. Currently supports easy setup of Target, RepoManager and + loading data (raw metadata and .solv files) into the pool. + + That's how it currently looks like: + + #include "TestSetup.h" + + BOOST_AUTO_TEST_CASE(WhatProvides) + { + TestSetup test( Arch_x86_64 ); // use x86_64 as system arch + test.loadTarget(); // initialize and load target + test.loadRepo( TESTS_SRC_DIR"/data/openSUSE-11.1" ); + + This is all you need to setup Target, RepoManager below some temp directory + and load the raw metadata into the pool. + + In case you want to setup the system below some fix directory, use: + + TestSetup test( "/tmp/mydir", Arch_x86_64 ); + + You directory is used as it is and not removed at the end. +\endverbatim + +*/ Added: trunk/libzypp/doc/autoinclude/g_BOOST.doc URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/g_BOOST.doc?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/g_BOOST.doc (added) +++ trunk/libzypp/doc/autoinclude/g_BOOST.doc Thu Oct 2 17:23:14 2008 @@ -0,0 +1,12 @@ +/** \namespace boost \ref BOOST +*/ +/** \defgroup BOOST Boost libraries. + +Boost provides free peer-reviewed portable C++ source libraries. +Several \c ::boost names were dragged or typedefed into +namespace \c ::zypp. +\see http://www.boost.org/ + +*/ + + Added: trunk/libzypp/doc/autoinclude/g_SATSOLVER.doc URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/g_SATSOLVER.doc?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/g_SATSOLVER.doc (added) +++ trunk/libzypp/doc/autoinclude/g_SATSOLVER.doc Thu Oct 2 17:23:14 2008 @@ -0,0 +1,7 @@ +/** \namespace zypp::sat \ref SATSOLVER +*/ +/** \defgroup SATSOLVER Satsolver interface + +Interface to sat-pool and sat-solver. + +*/ Added: trunk/libzypp/doc/autoinclude/groups.doc URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/groups.doc?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/groups.doc (added) +++ trunk/libzypp/doc/autoinclude/groups.doc Thu Oct 2 17:23:14 2008 @@ -0,0 +1,25 @@ +//////////////////////////////////////////////////////////////////////////////// +// Short or empty group definitions. Move them to a sepearate .doc file if +// more text is provided. +//////////////////////////////////////////////////////////////////////////////// +/*! \defgroup g_EnumerationClass Enumeration Class +*/ +//////////////////////////////////////////////////////////////////////////////// +/*! \defgroup g_RAII RAII solutions + \see http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization +*/ +//////////////////////////////////////////////////////////////////////////////// +/*! \defgroup g_CRTP CRTP solutions + \see http://en.wikipedia.org/wiki/Curiously_Recurring_Template_Pattern +*/ +//////////////////////////////////////////////////////////////////////////////// +/*! \defgroup g_BackenSpecific Backend Specific +*/ +//////////////////////////////////////////////////////////////////////////////// +//////////////////////////////////////////////////////////////////////////////// +/*! \defgroup g_Functor Filters and Functors +*/ +//////////////////////////////////////////////////////////////////////////////// +/*! \defgroup g_Algorithm Algorithms +*/ +//////////////////////////////////////////////////////////////////////////////// Added: trunk/libzypp/doc/autoinclude/notes/n_ResPool_nomorenameiter URL: http://svn.opensuse.org/viewcvs/zypp/trunk/libzypp/doc/autoinclude/notes/n_ResPool_nomorenameiter?rev=11232&view=auto ============================================================================== --- trunk/libzypp/doc/autoinclude/notes/n_ResPool_nomorenameiter (added) +++ trunk/libzypp/doc/autoinclude/notes/n_ResPool_nomorenameiter Thu Oct 2 17:23:14 2008 @@ -0,0 +1,71 @@ + +I tagged the byName iterator as deprecated, so the compiler tells you +where it is used. Please review the code and check whether byIdent is +an appropriate replacement. + + +-- +The 'old' zypp pool internally maintained a byName index, so it was a +fast way to iterate the pool by name and filter by kind to visit e.g. +all packages named foo: + + invokeOnEach( pool.byNameBegin( name ), pool.byNameEnd( name ), + resfilter::ByKind( kind ), + action() ); + + for_( it, pool.byNameBegin( name ), pool.byNameEnd( name ) ) + { + if ( (*it)->kind() == kind ) + { + ... + } + } + +This is no longer true. + + + +In contrary, byName now is a 'quite expensive' iteration. It's faster to +rewrite these loops using byIdent (and no filter): + + invokeOnEach( pool.byIdentBegin( kind, name ), + pool.byIdentEnd( kind, name ), + action() ); + + for_( it, pool.byIdentBegin( kind, name ), pool.byNameEnd( kind, name ) ) + { + ... + } + + +How to construct the byIdent iterator: + + ResPool::byIdentBegin( poolItem ) // using this poolItems kind and name + ResPool::byIdentBegin( kind, name ) // explicit kind and name + ResPool::byIdentBegin<Package>( name ) // or templated kind + + + +-- + +If you prefer using iterator in a for' loop, but dislike to figure out +the exact type of the iterator, you may find the 'for_' macro convenient: + + #include "zypp/base/Easy.h" + + for_( it, pool.byIdentBegin( kind, name ), + pool.byIdentEnd( kind, name ) ) + { + PoolItem copy = *it; + } + + +instead of: + + for ( ResPool::byIdent_iterator it = pool.byIdentBegin( kind, name ), + end = pool.byIdentEnd( kind, name ); + it != end, ++it ) + { + PoolItem copy = *it; + } + -- To unsubscribe, e-mail: zypp-commit+unsubscribe@opensuse.org For additional commands, e-mail: zypp-commit+help@opensuse.org