Re: [boost] [locale] Review: Reference documentation

Subject: Re: [boost] [locale] Review: Reference documentation
From: Artyom (artyomtnk_at_[hidden])
Date: 2011-04-22 16:27:07

> From: Gevorg Voskanyan <v_gevorg_at_[hidden]>
>
> [snip:multiple language fixes]

thanks

>
> "word_any      Any word including numbers, 0 is special flag, equivalent to 
>15." 
>
> What has 0  to do with word_any that it's being mentioned here? Isn't 15 the 
> value for  word_none?
>

I'll revisit it.
 
> [snip:multiple language fixes]

thanks

> "Return  the mark that token iterator points at." Shouldn't be break  
iterator?
> 

I'll check

> 
> It isn't specified what values compare functions return. E.g. is it  < 0, 0, > 
>0 
>
> or -1, 0, 1. Needs to be explained what kind of value is  returned in which 
>case.
> 

Good point, will be addressed

> classboost_1_1locale_1_1date__time__period__set.html:
> 
> Why are  the operations not commutative?

Actually not right, will be fixed.

> 
> I don't think BOOST_LOCALE_DECL needs to be in  documentation.
> 

I'll see how to get rid of it.

> 
> "sci or `scientific` --  display in scientific format"  why is scientific in 
> backticks and sci  not?

Remainings from markdown (originally tutorial was written using
markdown syntax)

Will be fixed.

> 
> "per or percent -- format percent value." What happens when a value  out of 
>range 
>
> [0..1] is passed in?
> 

The value 150% is valid as well :-)

> "locale -- with parameter -- switch  locale for current operation. This command 
>
> generates locale with formatting  facets giving more fine grained control of 
> formatting. For example: "   Where is the example?
> 

I'll take a look on it.

> What are the requirements for  Formattible?

I'll take a look on it as well.

> 
> "Generate codepage conversion  facets" Isn't "encoding" more  appropriate?
> 

Yes. 

> 
> "Default  constructor" Not exactly, can be called with a size_t argument as  
>well
> 

Good point, I'll revisit.

> operator<< not mentioned but should be as it is part of  the message class 
> interface
> 

I'll take a look if it can be done.

> 
> Inconsistent documentation for data  members here: some are documented in 
>Member 
>
> Data Documentation, the other in  the introduction.
> 

Noted, I'll look into

> 
> Sometimes qualified ids  make it harder to read. For example in 
> group__boundary.html the  boost::locale::boundary:: qualifiers make it really 
> hard for me to read the  important part here - the individual  names.
> 

Noted, I'll look into

Thanks for valuable comments.

Artyom