From 9f55c34850e108f84e4e1584f29c7a9b48fcdd60 Mon Sep 17 00:00:00 2001 From: Michael Andres Date: Thu, 2 Oct 2008 15:23:14 +0000 Subject: [PATCH] - Removed doxygen files from source tree. Additional documentation and related pages are now located in doc/autoinclude. --- doc/autodoc/CMakeLists.txt | 5 +- doc/autodoc/Doxyfile.cmake | 9 +- doc/autoinclude/CodeSnippets.doc | 122 +++++++++++++++++++++ doc/autoinclude/Mainpage.doc | 6 + doc/autoinclude/README | 54 +++++++++ doc/autoinclude/Testcases.doc | 39 +++++++ doc/autoinclude/g_BOOST.doc | 12 ++ doc/autoinclude/g_SATSOLVER.doc | 7 ++ doc/autoinclude/groups.doc | 25 +++++ .../autoinclude/notes}/n_ResPool_nomorenameiter | 0 zypp/@DOXYGEN/DOXYGEN.h | 72 ------------ zypp/@DOXYGEN/g_Algorithm | 0 zypp/@DOXYGEN/g_CodeSnippets | 117 -------------------- zypp/@DOXYGEN/g_Functor | 19 ---- zypp/@DOXYGEN/g_RAII | 0 zypp/@DOXYGEN/g_Resolvable | 45 -------- zypp/@DOXYGEN/g_ResolvableImpl | 0 zypp/@DOXYGEN/g_ResolvableImplIf | 0 18 files changed, 271 insertions(+), 261 deletions(-) create mode 100644 doc/autoinclude/CodeSnippets.doc create mode 100644 doc/autoinclude/Mainpage.doc create mode 100644 doc/autoinclude/README create mode 100644 doc/autoinclude/Testcases.doc create mode 100644 doc/autoinclude/g_BOOST.doc create mode 100644 doc/autoinclude/g_SATSOLVER.doc create mode 100644 doc/autoinclude/groups.doc rename {zypp/@DOXYGEN => doc/autoinclude/notes}/n_ResPool_nomorenameiter (100%) delete mode 100644 zypp/@DOXYGEN/DOXYGEN.h delete mode 100644 zypp/@DOXYGEN/g_Algorithm delete mode 100644 zypp/@DOXYGEN/g_CodeSnippets delete mode 100644 zypp/@DOXYGEN/g_Functor delete mode 100644 zypp/@DOXYGEN/g_RAII delete mode 100644 zypp/@DOXYGEN/g_Resolvable delete mode 100644 zypp/@DOXYGEN/g_ResolvableImpl delete mode 100644 zypp/@DOXYGEN/g_ResolvableImplIf diff --git a/doc/autodoc/CMakeLists.txt b/doc/autodoc/CMakeLists.txt index 4442a10..60c940c 100644 --- a/doc/autodoc/CMakeLists.txt +++ b/doc/autodoc/CMakeLists.txt @@ -8,8 +8,9 @@ ELSE ( NOT DOT ) 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 ) diff --git a/doc/autodoc/Doxyfile.cmake b/doc/autodoc/Doxyfile.cmake index 52daa4e..13cad58 100644 --- a/doc/autodoc/Doxyfile.cmake +++ b/doc/autodoc/Doxyfile.cmake @@ -8,7 +8,6 @@ PROJECT_NUMBER = @VERSION@ 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 @@ WARN_LOGFILE = #--------------------------------------------------------------------------- # 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 @@ DIRECTORY_GRAPH = NO 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 diff --git a/doc/autoinclude/CodeSnippets.doc b/doc/autoinclude/CodeSnippets.doc new file mode 100644 index 0000000..daa33a2 --- /dev/null +++ b/doc/autoinclude/CodeSnippets.doc @@ -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 diff --git a/doc/autoinclude/Mainpage.doc b/doc/autoinclude/Mainpage.doc new file mode 100644 index 0000000..e00d4c4 --- /dev/null +++ b/doc/autoinclude/Mainpage.doc @@ -0,0 +1,6 @@ +/** \namespace zypp libzypp +*/ +** \mainpage Welcome to libzypp + + +*/ \ No newline at end of file diff --git a/doc/autoinclude/README b/doc/autoinclude/README new file mode 100644 index 0000000..cc16030 --- /dev/null +++ b/doc/autoinclude/README @@ -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. diff --git a/doc/autoinclude/Testcases.doc b/doc/autoinclude/Testcases.doc new file mode 100644 index 0000000..2e59580 --- /dev/null +++ b/doc/autoinclude/Testcases.doc @@ -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 + +*/ diff --git a/doc/autoinclude/g_BOOST.doc b/doc/autoinclude/g_BOOST.doc new file mode 100644 index 0000000..df2fa86 --- /dev/null +++ b/doc/autoinclude/g_BOOST.doc @@ -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/ + +*/ + + diff --git a/doc/autoinclude/g_SATSOLVER.doc b/doc/autoinclude/g_SATSOLVER.doc new file mode 100644 index 0000000..97e67f0 --- /dev/null +++ b/doc/autoinclude/g_SATSOLVER.doc @@ -0,0 +1,7 @@ +/** \namespace zypp::sat \ref SATSOLVER +*/ +/** \defgroup SATSOLVER Satsolver interface + +Interface to sat-pool and sat-solver. + +*/ diff --git a/doc/autoinclude/groups.doc b/doc/autoinclude/groups.doc new file mode 100644 index 0000000..84c0a69 --- /dev/null +++ b/doc/autoinclude/groups.doc @@ -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 +*/ +//////////////////////////////////////////////////////////////////////////////// diff --git a/zypp/@DOXYGEN/n_ResPool_nomorenameiter b/doc/autoinclude/notes/n_ResPool_nomorenameiter similarity index 100% rename from zypp/@DOXYGEN/n_ResPool_nomorenameiter rename to doc/autoinclude/notes/n_ResPool_nomorenameiter diff --git a/zypp/@DOXYGEN/DOXYGEN.h b/zypp/@DOXYGEN/DOXYGEN.h deleted file mode 100644 index 557f599..0000000 --- a/zypp/@DOXYGEN/DOXYGEN.h +++ /dev/null @@ -1,72 +0,0 @@ -// -// -#warning DO NOT INCLUDE DOXYGEN.h IT CONTAINS JUST DOCUMENTATION STUFF -// -// -//////////////////////////////////////////////////////////////////////////////// -/*! \mainpage - -\section coding_sec Code snippets -\include g_CodeSnippets - -*/ -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_Resolvable Resolvable Objects - * \verbinclude g_Resolvable -*/ - -/*! \defgroup g_ResolvableImplIf Implementation interfaces - * \ingroup g_Resolvable - * \verbinclude g_ResolvableImplIf -*/ - -/*! \defgroup g_ResolvableImpl Implementations - * \ingroup g_Resolvable - * \verbinclude g_ResolvableImpl -*/ -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_EnumerationClass Enumeration Class - * \verbinclude g_EnumerationClass -*/ -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_RAII RAII solutions - * \see http://en.wikipedia.org/wiki/Resource_Acquisition_Is_Initialization - * \verbinclude g_RAII -*/ -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_CRTP CRTP solutions - * \see http://en.wikipedia.org/wiki/Curiously_Recurring_Template_Pattern - * \verbinclude g_CRTP -*/ -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_BackenSpecific Backend Specific - * \verbinclude g_BackenSpecific -*/ -//////////////////////////////////////////////////////////////////////////////// -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_Functor Filters and Functors - * \verbinclude g_Functor -*/ -//////////////////////////////////////////////////////////////////////////////// -/*! \defgroup g_Algorithm Algorithms - * \verbinclude g_Algorithm -*/ -//////////////////////////////////////////////////////////////////////////////// -/** \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/ - */ -/** \ref BOOST */ -namespace boost {} -//////////////////////////////////////////////////////////////////////////////// -/** \defgroup SATSOLVER Satsolver interface. - * Interface to sat-pool and sat-solver. - */ - namespace zypp - { - /** \ref SATSOLVER */ - namespace sat {} - } - diff --git a/zypp/@DOXYGEN/g_Algorithm b/zypp/@DOXYGEN/g_Algorithm deleted file mode 100644 index e69de29..0000000 diff --git a/zypp/@DOXYGEN/g_CodeSnippets b/zypp/@DOXYGEN/g_CodeSnippets deleted file mode 100644 index 9775c39..0000000 --- a/zypp/@DOXYGEN/g_CodeSnippets +++ /dev/null @@ -1,117 +0,0 @@ -// ////////////////////////////////////////////////////////////////////// -// 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; - } - - -// ////////////////////////////////////////////////////////////////////// -// 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 ); - diff --git a/zypp/@DOXYGEN/g_Functor b/zypp/@DOXYGEN/g_Functor deleted file mode 100644 index 167d860..0000000 --- a/zypp/@DOXYGEN/g_Functor +++ /dev/null @@ -1,19 +0,0 @@ -Just as reminder for me ( - /** */ - template - filter_iterator<_Filter, const_iterator> begin() const - { return make_filter_iterator( _Filter(), begin(), end() ); } - /** */ - template - filter_iterator<_Filter, const_iterator> begin( _Filter f ) const - { return make_filter_iterator( f, begin(), end() ); } - - /** */ - template - filter_iterator<_Filter, const_iterator> end() const - { return make_filter_iterator( _Filter(), end(), end() ); } - /** */ - template - filter_iterator<_Filter, const_iterator> end( _Filter f ) const - { return make_filter_iterator( f, end(), end() ); } -) diff --git a/zypp/@DOXYGEN/g_RAII b/zypp/@DOXYGEN/g_RAII deleted file mode 100644 index e69de29..0000000 diff --git a/zypp/@DOXYGEN/g_Resolvable b/zypp/@DOXYGEN/g_Resolvable deleted file mode 100644 index f60dc47..0000000 --- a/zypp/@DOXYGEN/g_Resolvable +++ /dev/null @@ -1,45 +0,0 @@ -Resolvables are reference counted objects. They are usually created and -provided by some kind of Source. They are accessed via smart Ptr classes, -which handle the reference counting. - - Resolvable (identification and dependencies) - ^ - ResObject (common data, mostly UI driven: summary descrition...) - ^ - Package, Patch,... (object specific data) - - -The Ptr types are typedefed inside the classes: - - Resolvable::Ptr (--> Resolvable*) - Resolvable::constPtr (--> const Resolvable*) - - ResObject::Ptr, ... accordingly. - -Automatic conversion is the same as with ordinary pointer. - -Available casts are: - - base::static_pointer_cast - base::const_pointer_cast - base::dynamic_pointer_cast - - - -Structure -========= - - base::ReferenceCounted - ^ - ------------------------------------------------------- - - Resolvable <---------+ - ^ backlink - ResObject +-----------ResObjectImplIf - ^ ^ - Package PackageImplIf - - ------------------------------------------------------- - ^ ^ - ResImplConnect --------> MyPackageImplementation - diff --git a/zypp/@DOXYGEN/g_ResolvableImpl b/zypp/@DOXYGEN/g_ResolvableImpl deleted file mode 100644 index e69de29..0000000 diff --git a/zypp/@DOXYGEN/g_ResolvableImplIf b/zypp/@DOXYGEN/g_ResolvableImplIf deleted file mode 100644 index e69de29..0000000 -- 2.7.4