Standard header format.

[llewelly@xmission.com]

"Steven T. Hatton" <hattons@globalsymmetry.com> writes:

> On Sunday 06 June 2004 02:18, Gabriel Dos Reis wrote:
> > "Steven T. Hatton" <hattons@globalsymmetry.com> writes:
> > | There are many C++ programmers who have suggested to me the best way
> > | to learn  what the standard headers probide is to look a them.
> >
> > That definitely is not the best way.  It is one of the worst way.
> 
> If there are actually header files in the traditional sense that look like 
> this:
> 
> //http://www.itga.com.au/~gnb/wp/cd2/lib-strings.html
> //http://www.itga.com.au/~gnb/wp/cd2/
>   struct
>        char_traits<char>
>   namespace std {
>     template<>
>     struct char_traits<char> {
>       typedef char        char_type;
>       typedef int         int_type;
>       typedef streamoff   off_type;
>       typedef streampos   pos_type;
>       typedef mbstate_t   state_type;
> 
>       static void assign(char_type& c1, const char_type& c2);
>       static bool eq(const char_type& c1, const char_type& c2);
>       static bool lt(const char_type& c1, const char_type& c2);
> 
>       static int compare(const char_type* s1, const char_type* s2, size_t n);
>       static size_t length(const char_type* s);
>       static const char_type* find(const char_type* s, int n,
>                                    const char_type& a);
>       static char_type* move(char_type* s1, const char_type* s2, size_t n);
>       static char_type* copy(char_type* s1, const char_type* s2, size_t n);
>       static char_type* assign(char_type* s, size_t n, char_type a);
> 
>       static int_type not_eof(const int_type& c);
>       static char_type to_char_type(const int_type& c);
>       static int_type to_int_type(const char_type& c);
>       static bool eq_int_type(const int_type& c1, const int_type& c2);
>       static state_type get_state(pos_type pos);
>       static int_type eof();
>     };
>   }
> 
> for example, then looking at the "standard headers" would be a worthwhile 
> means of determining what is provided by the Standard Library. I believe the 
> people who have suggested looking at the Standard Headers were expecting me 
> to find them in the form presented above.  I am not saying they /should/ 
> expect that.  I'm saying they /do/ expect that.

If the above is intended to inform programmers as the the interface of
    the library, it belongs in the *documentation*, not in the header
    files. Most programmers only look at the header files when the
    documentation is woefully inadequate. If a C programmer needs to
    know the interface of printf, he looks in the man or info pages
    for his system's libc. He doesn't look at the header files, which
    in all frankness he probably can't understand anyway. It should be
    the same for C++ programmers.