Re: [Gnash-commit] gnash ChangeLog libbase/utf8.h server/edit_text...

[strk]

On Thu, Feb 07, 2008 at 04:15:34PM +0000, Benjamin Wolsey wrote:

> Log message:
>       Comments and minor cleanup.

Great ! :)


> +/// Utilities to convert between std::string and std::wstring.
> +/// Strings in Gnash are generally stored as std::strings.

Just a tip here. If you separate the first line of the description
from the second using a 2-slashes comment, as in:

 /// Utilities to convert between std::string and std::wstring.
 //
 /// Strings in Gnash are generally stored as std::strings.

Doxygen will automatically turn the first line into a "short-description"
for the namespace, and still give you access to the full description
(including first line) when you click on the namespace.
Failing to explicitly set a "brief" description (there are other ways 
to do the same too, but I find this being the nicer) will omit
any short description from the "namespaces" page.

> +/// edit_text_character, ord() and chr().
>  
>  namespace utf8

Worth testing if the space between last line of the comment and the actual
namespace keyword confuses Doxygen or not (make apidoc under doc/).

> +     /// Converts a canonical std::string with multibyte characters into
> +     /// a std::wstring.
> +     /// @ param str the canonical string to convert
> +     /// @ param version the SWF version, used to decide how to decode the 
> string.

In this case, since the short-description spans more then a single line, you 
can 
explicitly tag it, as in:

  /// \brief
  /// Converts a canonical std::string with multibyte characters into
  /// a std::wstring.
  ///
  /// @ param str the canonical string to convert

Keep up the good work !

--strk;