Improve regex doc

diff --git a/zypp/base/Regex.h b/zypp/base/Regex.h
index 9a934cc601c84cc8c9accdc79b374fba910d20bc..7eb01b0dcde355a2924722f75974c66f9b92e8f5 100644 (file)
--- a/zypp/base/Regex.h
+++ b/zypp/base/Regex.h
@@ -18,73 +18,82 @@
 
 #include "zypp/base/Exception.h"
 
-///////////////////////////////////////////////////////////////////
+//////////////////////////////////////////////////////////////////
 namespace zypp
-{ /////////////////////////////////////////////////////////////////
-  ///////////////////////////////////////////////////////////////////
-  /** String related utilities and \ref ZYPP_STR_REGEX.
-   \see \ref ZYPP_STR_REGEX
-  */
+{
+  //////////////////////////////////////////////////////////////////
+  /// \namespace str
+  /// \brief String related utilities and \ref ZYPP_STR_REGEX.
   namespace str
-  { /////////////////////////////////////////////////////////////////
-
-    ///////////////////////////////////////////////////////////////////
-    /** \defgroup ZYPP_STR_REGEX Regular expressions
-     *
-     * \brief Namespace zypp::str regular expressions \b using the glibc regex library.
-     * \see also \ref sat::AttrMatcher string matcher supporing regex, globing, etc.
-     *
-     * \code
-     *  str::regex rxexpr( "^(A)?([0-9]*) im" );
-     *  str::smatch what;
-     *
-     *  std::string mytext( "Y123 imXXXX" );
-     *  if ( str::regex_match( mytext, what, rxexpr ) )
-     *  {
-     *    MIL << "MATCH '" << what[0] << "'" << endl;
-     *    MIL << " subs: " << what.size()-1 << endl;
-     *    for_( i, 1U, what.size() )
-     *      MIL << "      [" << i << "] " << what[i] << endl;
-     *  }
-     *  else
-     *  {
-     *    WAR << "NO MATCH '" << rxexpr << "' in '" <<  mytext << endl;
-     *  }
-     * \endcode
-     */
+  {
+    //////////////////////////////////////////////////////////////////
+    /// \defgroup ZYPP_STR_REGEX Regular expression matching
+    /// \brief Regular expressions using the glibc regex library.
+    ///
+    /// \see also \ref sat::AttrMatcher string matcher also supporting globing, etc.
+    ///
+    /// \code
+    ///  str::regex rxexpr( "^(A)?([0-9]*) im" );
+    ///  str::smatch what;
+    ///
+    ///  std::string mytext( "Y123 imXXXX" );
+    ///  if ( str::regex_match( mytext, what, rxexpr ) )
+    ///  {
+    ///    MIL << "MATCH '" << what[0] << "'" << endl;
+    ///    MIL << " subs: " << what.size()-1 << endl;
+    ///    for_( i, 1U, what.size() )
+    ///      MIL << "      [" << i << "] " << what[i] << endl;
+    ///  }
+    ///  else
+    ///  {
+    ///    WAR << "NO MATCH '" << rxexpr << "' in '" <<  mytext << endl;
+    ///  }
+    /// \endcode
+    //////////////////////////////////////////////////////////////////
 
     typedef Exception regex_error;
 
     class smatch;
     class regex;
 
-    /**
-     * \ingroup ZYPP_STR_REGEX
-     */
-    bool regex_match(const char * s, str::smatch& matches, const regex& regex);
-    inline bool regex_match(const std::string& s, str::smatch& matches, const regex& regex)
+    //////////////////////////////////////////////////////////////////
+    /// \brief Regular expression matching
+    ///
+    /// \ingroup ZYPP_STR_REGEX
+    /// \relates regex
+    /// Return whether a \ref regex matches a specific string. An optionally
+    /// passed \ref smatch object will contain the match reults.
+    //////////////////////////////////////////////////////////////////
+    bool regex_match( const char * s, smatch & matches, const regex & regex );
+
+    /** \copydoc regex_match \relates regex \ingroup ZYPP_STR_REGEX */
+    inline bool regex_match(const std::string & s, smatch & matches, const regex & regex)
     { return regex_match( s.c_str(), matches, regex ); }
 
-    /**
-     * \ingroup ZYPP_STR_REGEX
-     */
-    bool regex_match(const char * s, const regex& regex);
-    inline bool regex_match(const std::string& s, const regex& regex)
+    /** \copydoc regex_match \relates regex \ingroup ZYPP_STR_REGEX */
+    bool regex_match( const char * s, const regex & regex );
+
+    /** \copydoc regex_match \relates regex \ingroup ZYPP_STR_REGEX */
+    inline bool regex_match( const std::string & s, const regex & regex )
     { return regex_match( s.c_str(), regex ); }
 
-    /**
-     * \ingroup ZYPP_STR_REGEX
-     */
-    class regex {
+    //////////////////////////////////////////////////////////////////
+    /// \class regex
+    /// \brief Regular expression
+    ///
+    /// \ingroup ZYPP_STR_REGEX
+    //////////////////////////////////////////////////////////////////
+    class regex
+    {
     public:
 
       enum RegFlags {
-        optimize = 0,
-        match_extra = 0,
-        icase = REG_ICASE,
-        nosubs = REG_NOSUB,
-        match_extended = REG_EXTENDED,
-        normal = 1<<16
+        optimize       = 0,            ///< \deprecated legacy, obsolete
+        match_extra    = 0,            ///< \deprecated legacy, obsolete
+        icase          = REG_ICASE,    ///< Do not differentiate case
+        nosubs         = REG_NOSUB,    ///< Support for substring addressing of matches is not required
+        match_extended = REG_EXTENDED, ///< Use POSIX Extended Regular Expression syntax when interpreting regex.
+        normal         = 1<<16         ///< \deprecated legacy, use match_extended
       };
 
       regex();
@@ -125,10 +134,19 @@ namespace zypp
     inline std::ostream & operator<<( std::ostream & str, const regex & obj )
     { return str << obj.asString(); }
 
-    /**
-     * \ingroup ZYPP_STR_REGEX
-     */
-    class smatch {
+    //////////////////////////////////////////////////////////////////
+    /// \class smatch
+    /// \brief Regular expression match result
+    ///
+    /// \ingroup ZYPP_STR_REGEX
+    ///
+    /// Index \c n=0 returns the string object representing the character
+    /// sequence that matched the whole regular expression.
+    /// If \c n is out of range, or if \c n is an unmatched sub-expression,
+    /// then an empty string is returned.
+    //////////////////////////////////////////////////////////////////
+    class smatch
+    {
     public:
       smatch();
 
@@ -140,12 +158,8 @@ namespace zypp
       regmatch_t pmatch[12];
     };
 
-
-
-    /////////////////////////////////////////////////////////////////
   } // namespace str
-  ///////////////////////////////////////////////////////////////////
-  /////////////////////////////////////////////////////////////////
+  //////////////////////////////////////////////////////////////////
 } // namespace zypp
-///////////////////////////////////////////////////////////////////
+//////////////////////////////////////////////////////////////////
 #endif // ZYPP_BASE_STRING_H