Merge pull request #223 from bitshares/fix-doxygen-warnings

Fix Doxygen warnings

include/fc/asio.hpp

@@ -1,5 +1,4 @@
 /**
- *  @file fc/cmt/asio.hpp
  *  @brief defines wrappers for boost::asio functions
  */
 #pragma once

include/fc/exception/exception.hpp

@@ -373,7 +373,8 @@ namespace fc
 /**
  *  @def FC_THROW_EXCEPTION( EXCEPTION, FORMAT, ... )
  *  @param EXCEPTION a class in the Phoenix::Athena::API namespace that inherits
- *  @param format - a const char* string with "${keys}"
+ *  @param FORMAT a const char* string with "${keys}"
+ *  @param ... other parameters
  */
 #define FC_THROW_EXCEPTION( EXCEPTION, FORMAT, ... ) \
   FC_MULTILINE_MACRO_BEGIN \

include/fc/io/buffered_iostream.hpp

@@ -31,7 +31,7 @@ namespace fc
          *  @pre buf != nullptr
          *  @throws fc::eof if at least 1 byte cannot be read
          **/
-        virtual std::size_t     readsome( char* buf, std::size_t len );
+        virtual size_t          readsome( char* buf, size_t len );
         virtual size_t          readsome( const std::shared_ptr<char>& buf, size_t len, size_t offset );
 
         /**

include/fc/log/log_message.hpp

@@ -109,6 +109,8 @@ namespace fc
          log_message();
          /**
           *  @param ctx - generally provided using the FC_LOG_CONTEXT(LEVEL) macro
+          *  @param format - the format
+          *  @param args - the arguments
           */
          log_message( log_context ctx, std::string format, variant_object args = variant_object() );
          ~log_message();

include/fc/reflect/reflect.hpp

@@ -113,7 +113,7 @@ struct Derivation_reflection_transformer {
 /// Macro to transform reflected fields of a base class to a derived class and concatenate them to a type list
 #define FC_CONCAT_BASE_MEMBER_REFLECTIONS(r, derived, base) \
    ::add_list<typelist::transform<reflector<base>::members, impl::Derivation_reflection_transformer<derived>>>
-/// Macro to concatenate a new @ref field_reflection to a typelist
+/// Macro to concatenate a new @c field_reflection to a typelist
 #define FC_CONCAT_MEMBER_REFLECTION(r, container, idx, member) \
    ::add<typename impl::Reflect_type<container>::template with_field_type<decltype(container::member)> \
                                                ::template at_index<idx> \
@@ -298,6 +298,7 @@ template<> struct get_typename<ENUM>  { static const char* name()  { return BOOS
  *  @brief Specializes fc::reflector for TYPE where
  *         type inherits other reflected classes
  *
+ *  @param TYPE - the type to reflect
  *  @param INHERITS - a sequence of base class names (basea)(baseb)(basec)
  *  @param MEMBERS - a sequence of member names.  (field1)(field2)(field3)
  */
@@ -379,6 +380,7 @@ template<> struct reflector<TYPE> {\
  *  @def FC_REFLECT(TYPE,MEMBERS)
  *  @brief Specializes fc::reflector for TYPE
  *
+ *  @param TYPE - the type to reflect
  *  @param MEMBERS - a sequence of member names.  (field1)(field2)(field3)
  *
  *  @see FC_REFLECT_DERIVED

include/fc/reflect/typelist.hpp

@@ -154,9 +154,9 @@ template<std::size_t count>
 using make_sequence = typename impl::make_sequence<count>::type;
 
 /// Template to build typelists using the following syntax:
-/// builder<>::type::add<T1>::add<T2>::add<T3>[...]::finalize
+/// @code builder<>::type::add<T1>::add<T2>::add<T3>[...]::finalize @endcode
 /// Or:
-/// builder<>::type::add_list<list<T1, T2>>::add_list<T3, T4>>[...]::finalize
+/// @code builder<>::type::add_list<list<T1, T2>>::add_list<T3, T4>>[...]::finalize @endcode
 template<typename List = list<>>
 struct builder {
    template<typename NewType> using add = typename builder<typename impl::concat<List, list<NewType>>::type>::type;

include/fc/thread/parallel.hpp

@@ -92,6 +92,7 @@ namespace fc {
     *  that can be used to wait on the result.
     *
     *  @param f the operation to perform
+    *  @param desc task name
     */
    template<typename Functor>
    auto do_parallel( Functor&& f, const char* desc FC_TASK_NAME_DEFAULT_ARG ) -> fc::future<decltype(f())> {

include/fc/variant.hpp

@@ -217,6 +217,7 @@ namespace fc
         variant( std::nullptr_t, uint32_t max_depth = 1 );
 
         /// @param str - UTF8 string
+        /// @param max_depth - the maximum depth to recurse into
         variant( const char* str, uint32_t max_depth = 1 );
         variant( char* str, uint32_t max_depth = 1 );
         variant( wchar_t* str, uint32_t max_depth = 1 );
@@ -703,4 +704,4 @@ namespace fc
 #include <fc/reflect/reflect.hpp>
 FC_REFLECT_TYPENAME( fc::variant )
 FC_REFLECT_ENUM( fc::variant::type_id, (null_type)(int64_type)(uint64_type)(double_type)(bool_type)(string_type)(array_type)(object_type)(blob_type) )
-FC_REFLECT( fc::blob, (data) );
+FC_REFLECT( fc::blob, (data) )

src/crypto/city.cpp

@@ -102,7 +102,9 @@ inline uint64_t Hash128to64(const uint128_t& x) {
 
 #else
 
+/// @cond IGNORE_WARNING
 #include <byteswap.h>
+/// @endcond
 
 #endif
 

src/crypto/sha1.cpp

@@ -11,14 +11,14 @@ namespace fc
 {
 
 sha1::sha1() { memset( _hash, 0, sizeof(_hash) ); }
-sha1::sha1( const string& hex_str ) {
+sha1::sha1( const std::string& hex_str ) {
   fc::from_hex( hex_str, (char*)_hash, sizeof(_hash) );  
 }
 
 string sha1::str()const {
   return fc::to_hex( (char*)_hash, sizeof(_hash) );
 }
-sha1::operator string()const { return  str(); }
+sha1::operator std::string()const { return  str(); }
 
 char* sha1::data()const { return (char*)&_hash[0]; }
 
@@ -37,7 +37,7 @@ sha1 sha1::hash( const char* d, uint32_t dlen ) {
   e.write(d,dlen);
   return e.result();
 }
-sha1 sha1::hash( const string& s ) {
+sha1 sha1::hash( const std::string& s ) {
   return hash( s.c_str(), s.size() );
 }
 

src/crypto/sha512.cpp

@@ -10,14 +10,14 @@
 namespace fc {
 
     sha512::sha512() { memset( _hash, 0, sizeof(_hash) ); }
-    sha512::sha512( const string& hex_str ) {
+    sha512::sha512( const std::string& hex_str ) {
       fc::from_hex( hex_str, (char*)_hash, sizeof(_hash) );  
     }
 
     string sha512::str()const {
       return fc::to_hex( (char*)_hash, sizeof(_hash) );
     }
-    sha512::operator string()const { return  str(); }
+    sha512::operator std::string()const { return  str(); }
 
     char* sha512::data()const { return (char*)&_hash[0]; }
 
@@ -36,7 +36,7 @@ namespace fc {
       e.write(d,dlen);
       return e.result();
     }
-    sha512 sha512::hash( const string& s ) {
+    sha512 sha512::hash( const std::string& s ) {
       return hash( s.c_str(), s.size() );
     }
 

src/io/json.cpp

@@ -475,9 +475,21 @@ namespace fc
    }
 
    /**
-    *  Convert '\t', '\a', '\n', '\\' and '"'  to "\t\a\n\\\""
+    *  @brief Escape a string
     *
-    *  All other characters are printed as UTF8.
+    *  * A quote is added to the beginning and a quote is added to the end
+    *  * The following characters are converted specially:
+    *    @code
+    *      '\b' -> "\b"
+    *      '\f' -> "\f"
+    *      '\n' -> "\n"
+    *      '\r' -> "\r"
+    *      '\t' -> "\t"
+    *      '\\' -> "\\"
+    *      '\"' -> "\""
+    *    @endcode
+    *  * other control characters are printed as UTF8
+    *  * printable characters are printed as is
     */
    void escape_string( const string& str, ostream& os )
    {

src/log/console_defines.h

@@ -1,13 +1,16 @@
 #ifndef _MACE_CMT_CONSOLE_DEFINES_H_
 #define _MACE_CMT_CONSOLE_DEFINES_H_
 
-/// @cond INTERNAL_DEV
+
 /**
     @file console_defines.h
     This header contains definitions for console styles and colors.
     @ingroup tconsole
 */
 
+#ifdef COLOR_CONSOLE
+
+#ifndef WIN32
 
 /**
     @defgroup console_styles Console Styles
@@ -18,9 +21,6 @@
     support styled text.
     @{
 */
-#if COLOR_CONSOLE
-
-#ifndef WIN32
 
 /**
     @def CONSOLE_DEFAULT
@@ -269,14 +269,25 @@
 */
 #define CONSOLE_WHITE_BG "\033[47m"
 
+/// @}
 
+#else // if defined WIN32
 
-#else // WIN32
 #include <winsock2.h>
 #include <windows.h>
-//#include <stdlib.h>
 #include <conio.h>
 
+/**
+    @defgroup console_styles Console Styles
+    @brief Defines styles that can be used within text printed to the Console.
+
+    Note that styles will not show up when printing to files (in fact, you will
+    get a lot of garbage characters if you do this). Also, not all consoles
+    support styled text.
+    @{
+*/
+
+
 /**
     @def CONSOLE_DEFAULT
     @brief Sets all styles and colors to the console defaults.
@@ -523,11 +534,13 @@
     (const char*)
 */
 #define CONSOLE_WHITE_BG "\033[47m"
-#endif
-
 
 /// @}
-#else // On Window's no color output WIN32
+
+#endif // WIN32
+
+#else // no COLOR_CONSOLE
+
 #define CONSOLE_DEFAULT ""
 #define CONSOLE_BOLD ""
 #define CONSOLE_HALF_BRIGHT ""
@@ -555,7 +568,8 @@
 #define CONSOLE_CYAN_BG  ""
 #define CONSOLE_WHITE_BG  ""
 
-/// @}
-/// @endcond INTERNAL_DEV
-#endif // NOT DEFINED WIN32
+
+
+#endif // COLOR_CONSOLE
+
 #endif // _BOOST_CMT_CONSOLE_DEFINES_H_

src/network/url.cpp

@@ -101,7 +101,7 @@ namespace fc
       return ss.str();
   }
 
-  url::url( const std::string& u )
+  url::url( const string& u )
   :my( std::make_shared<detail::url_impl>() )
   {
     my->parse(u);

src/thread/context.hpp

@@ -122,6 +122,7 @@ namespace fc {
     /**
      *  @todo Have a list of promises so that we can wait for
      *    P1 or P2 and either will unblock instead of requiring both
+     *  @param p - the promise
      *  @param req - require this promise to 'unblock', otherwise try_unblock
      *     will allow it to be one of many that could 'unblock'
      */

src/thread/mutex.cpp

@@ -28,7 +28,8 @@ namespace fc {
   }
 
   /**
-   *  @param  last_context - is set to the next context to get the lock (the next-to-last element of the list)
+   *  @param  list_head - the head of the list
+   *  @param  context_to_unblock - is set to the next context to get the lock (the next-to-last element of the list)
    *  @return the last context (the one with the lock)
    */
   static fc::context* get_tail( fc::context* list_head, fc::context*& context_to_unblock ) {