date::day_of_week documentation is unhelpful

[russell.silva@…]

The Gregorian date documentation for the day_of_week method is unhelpful. It's not clear what the return type of the method is; it's not immediately obvious what a greg_day_of_week is. The example does not help, since it does not use the method at all. It turns out that the method returns an integer, but there is no documentation as to which day corresponds to which integer return value.

http://www.boost.org/doc/libs/1_43_0/doc/html/date_time/gregorian.html#date_time.gregorian.date_class

[viboes]

It returns

! An enumeration of weekday names enum weekdays {Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday};

defined in date_defs/hpp.

I agree the documentation can be improved.

[anonymous]

The whole boost.date_time documentation is an horrible mess. It should be entirely rewritten from scratch.

[anonymous]

In fact, I have to sadly agree to the last comment. The documentation is impossible to understand. It took me 1h at work to figure out what was the result of day_of_week() !!!!! How can we help ?

[TCN]

Documentation should have an example like this (tested with boost 1.45.0):

#include <iostream>
#include <boost/date_time/gregorian/gregorian.hpp>
using namespace boost::gregorian;
using namespace std;
...
// Inside main() or some other function
date d(2012, Apr, 19);
cout << "Date : " << d << endl;
greg_weekday wd(d.day_of_week());
greg_day_of_year_rep yd(d.day_of_year());
cout << "Day of week : " << wd                          // or wd.as_short_string()
     << " (full name : " << wd.as_long_string() << ")"  // returns a char*, as above
     << " (as number : " << wd.as_number() << ")"       // returns an unsigned short
     << endl;
cout << "Day of year : " << yd << endl;                 // returns an unsigned short

And/or it should point the user to greg_weekday.hpp, greg_day_of_year.hpp

(Naming inconsistencies, yuck!)