[boost] [locale] Review: Reference documentation

Subject: [boost] [locale] Review: Reference documentation
From: Gevorg Voskanyan (v_gevorg_at_[hidden])
Date: 2011-04-22 11:09:07

group__boundary.html:

s/like and sentence boundaries/line and sentence boundaries/

s/alalisys/analysis/

s/Find a positions/Find positions/

s/like break is required/line break is required/

s/possible followed by/possibly followed by/

"Either first or second sentence break type;." redundant ;

"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?

s/Maximal used mask/All types of words mask/   maybe?

structboost_1_1locale_1_1boundary_1_1break__info.html:

s/begging/beginning/

classboost_1_1locale_1_1boundary_1_1boundary__indexing_3_01char_01_4.html:

s/analisys/analysis/

classboost_1_1locale_1_1boundary_1_1mapping.html:

s/Class the holds/Class that holds/

"When the object is created in creates index" s/in/it/  ?

"it is used mostly together ..." capitalize the first letter

s/vise versa/vice versa/   many occurrences

"you can set the mask value sentence_term" sentence_term should be a link. In 
general the whole documentation should be scanned to add links where 
appropriate.

"would not be compatible with old ones"  add a period

classboost_1_1locale_1_1boundary_1_1token__iterator.html:

s/white spaces punctuation/white spaces, punctuation/

s/Opposite of ===/Negation of ==/

classboost_1_1locale_1_1boundary_1_1break__iterator.html:

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

group__collation.html:

"This module that introduces collation related classes" Rephrasing needed

classboost_1_1locale_1_1collator__base.html:

s/a base class that included/a base class that includes/

What about providing synonyms for collation levels like  base_letters = primary, 
letters_accents = secondary, etc.
classboost_1_1locale_1_1collator.html:

s/stc::collate/std::collate/

s/two strings in rage/two strings in range/   Strings in rage can be harmful :D

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.

group__convert.html:

s/various function/various functions/

s/It does not takes/It does not take/  many occurrences

group__date__time.html:

s/a enum/an enum/

s/perood/period/

date_time now(time(0),hebrew_calendar)
  cout << "Year:" t / perood::year <<" Full Date:"<< as::date_time << t;
Should be:
date_time now(time(0),hebrew_calendar);
  cout << "Year:" << t / period::year <<" Full Date:"<< as::date_time << t;

classboost_1_1locale_1_1date__time__period__set.html:

Why are the operations not commutative?

s/should be in range [0,size)/should be in range [0,size())/

classboost_1_1locale_1_1calendar.html:

s/Get grates possible/Get greatest possible/

classboost_1_1locale_1_1date__time.html:

s/opject/object/  many occurrences

s/perios/period/

"Check if the current time is in daylight saving time"  Current time or the time 
represented by *this? In all other places, references to "current time" need to 
be checked.

s/ingnores/ignores/  many occurrences

s/substract/subtract/  many occurrences

s/valrious/various/

s/gettimeofdat/gettimeofday/

namespaceboost_1_1locale_1_1period.html:

"hour_12     12 clock hour [0..11]"  AFAIU the range of hours in AM/PM notation 
is [1..12], no?

s/withing/within/

s/First day if week/First day of week/

s/convers period_type/convert period_type/

namespaceboost_1_1locale_1_1time__zone.html:

"namespace that holds function for operating global time zone identifier" Needs 
rephrasing, perhaps "namespace that holds functions for operating with global 
time zone"

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

s/returing/returning/

classboost_1_1locale_1_1basic__format.html:

s/curl brackets/curly braces/

s/hight/height/

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

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

"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?

What are the requirements for Formattible?

group__format.html:

s/Definiton/Definition/  2 occurrences

s/It use locale and of \a out stream/It uses locale of \a out stream/

group__manipulators.html:

s/is treaded as/is treated as/  many occurrences

namespaceboost_1_1locale.html:

s/namespae/namespace/

s/independed/independent/  multiple occurrences

s/typr/type/

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

namespaceboost_1_1locale_1_1util.html:

s/the codecvt faced/the codecvt facet/
s/it know/it knows/

s/can can/can/  two occurrences

classboost_1_1locale_1_1calendar__facet.html:

s/Locale id (for work with std::locale/Locale id (needed to work with 
std::locale)/

classboost_1_1locale_1_1generator.html:

s/protable/portable/

s/if it deals with/if dealing with/

classboost_1_1locale_1_1hold__ptr.html:

s/transfered/transferred/  two occurrences

classboost_1_1locale_1_1info.html:

s/Is underlying encoding is UTF-8/True if the underlying encoding is UTF-8/

classboost_1_1locale_1_1localization__backend.html:

s/swithc/switch/

s/differnt/different/

s/priority/priotiry/

classboost_1_1locale_1_1localization__backend__manager.html:

s/avalible/available/

s/combing/combining/

classboost_1_1locale_1_1message__format.html:

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

structboost_1_1locale_1_1message.html:

"Message class can be explicitly converter to string class"  converted

s/defailt/default/

\ a --> \a for doxygen, 3 occurrences

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

A link to group__message.html would be helpful here

structboost_1_1locale_1_1gnu__gettext_1_1messages__info.html:

s/sturcture/structure/

s/this structure not useful/this structure is not useful/

s/Igronred/Ignored/

s/for narror/For narrow/

s/seach/search/

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

"Locale category, is set by default LC_MESSAGES, but ma."  Incomplete?

General remarks:

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.

Gevorg