bjarne wrote:

> kuy...@wizard.net wrote:
>=20
>> If the idea that "the proper way to understand an API is to read the
>> header(s) by which it is implemented" is in fact pervasive in
>> TC++PL(SE), then ...
>=20
> It is not, obviously not,

I have to observe that we are dealing with excerpts of a lengthy discussi=
on,
and I did not make the above statement shown in quotations.  I would not
have made that statement in the absolute terms it uses.  Here is my
reasoning for the statement "it's pervasive" and what I really meant is
pervasive.  I can't quote any specific statements in TC++PL(SE) regarding
readability, or who the intended audience of a program is.  Perhaps it's
simply a result of my introductory computer science courses, but I hold
fast to the idea that computer programs are written in higher level
languages in order to facilitate communication between programmers.  To m=
e
that implies that the content of a header or other source file is intende=
d
to be read by other programmers. =20

I am confident that you do discuss the concept of a user's interface.  Yo=
u
do it in the context of discussing namespaces, as well as in the context =
of
discussing header files.  For example in =A78.2.4.1, and =A79.3.2.  Am I
mistaken to believe that a user of the interface would not be expected to
read the header providing the interface?  In =A724.4.2 you also discuss
aspects of design related to interfaces.  The first quality listed for an
ideal interface is that it "presents a complete and coherent set of
concepts to a user".  I understand that there are times when class names,
function names, variable names, etc. cannot communicate all that is neede=
d
in order to program against an interface.  Nonetheless, I have to ask, am=
 I
wrong in understanding that you intend for the user of the interface to
actually look at the source file where it is presented?

I will also observe that you often present excerpts from the Standard
Headers as a means of communicating what they provide, and how they shoul=
d
be used.  If I collect all of the assumptions I have stated above, I have
to conclude that you intend for people to examine the source code
declaration of an interface as a means of learning how it is to be used.=20
The evidence for this is scattered throughout your book, so I feel
justified in saying it is pervasive.

> but I *do* recommend that people look at=20
> their headers. Sometimes the headers are incomprehensible, and they
> always containe more crud than we'd like to see (more than even the
> implementers would like there). However, once a programmer/student has
> exhaused the available documentation, it is a good healthy practice to
> have a look at the headers (though the file or maybe through an IDE).
> They may not be very clear, they may be confusing, but they're there
> and one can learn something from them - often they are more easily
> accessible than the standard or (my:-) book. I carry those on my
> laptop, but not everybody does. Obviously, the standard library headers
> are *not* the definition of the standard library. There are often
> omissions in a particular set of headers, even more often non-standard
> extensions, and the semantics is most often left obscure. However,
> after an initial learning period, we can't protect new programmers from
> the messy world, and the standard library headers are often worthwhile
> reading.=20

I am of the opinion that the Standard Library Headers should be arranged =
and
composed as much as possible to present to the user the kind of ideal
interface described in =A724.4.2.  Even where these Headers are used by o=
ther
parts of the Standard Library, they should serve as a user interface in
much the same way they do for the application programmer.

> Headers is not the first place to look for understanding a=20
> library, but it is a place where it is good to look occationally - or
> we might end up with an overly idealized or legalistic view of
> programming.

I'm not sure I agree that looking at the Headers as a first step in
understanding a library is wrong.  Especially if they approximate the fir=
st
requirement stated above for an ideal interface.

Take the simple case of a std::gslice from <valarray>.

 class gslice {
  public:
    gslice();
    gslice(size_t s, const valarray<size_t>& l, const valarray<size_t>& d=
);
    size_t           start() const;
    valarray<size_t> size() const;
    valarray<size_t> stride() const;
  };

Nevermind that "size", "length" and "distance" are not spelled out as the=
y
should be.  By looking at this class definition, I may not get a complete
understanding of what it provides, but I do see its complete interface, a=
nd
learn a great deal about it.  I can formulate questions in my mind
regarding those things which are not evident from the interface of the
class.  After examining the definition in <valarray>, assuming the
documentation is not in a comment block above the definition, when I do
look at the documentation, it is likely I will have a much better concept
of what it describes.
=20
> Knowing that we look may also occationally help encourage an
> implementer not to make headers more messy than necessary.
>=20
There are many interesting considerations regarding what the implementati=
on
exposes to the application programmer through the Standard Headers.  One
aspect of the concept of a class's interface is not what it exposes, what
what it hides. To take another example from <valarray>

  template <class T> class gslice_array {
  public:
    typedef T value_type;
    void  operator=3D (const   valarray<T>&) const;
    //...
    void operator=3D(const T&);
    ?gslice_array();
  private:
    gslice_array();
    gslice_array(const gslice_array&);
    gslice_array& operator=3D(const gslice_array&);
  };

The fact that the constructors and assignment operators are private is
information useful to the user, even though these are by definition not
part of the interface.  If the programmer is not aware that these are
private he or she could reasonably assume they are available for use.

Private member variables are likely to appear in class definitions, but a=
re
of no immediate relevance to the user.  One view of an idealized interfac=
e
would have such variables hidden away by means of indirection.  I suspect
few implementers or application programmers would want that approach take=
n
with the Standard Library in view of the fact that there would be an
indirection penalty to pay.

The reason I'm mentioning these things is because they seem relevant in
evaluating the degree to which the Standard Headers can be understood as
and treated as application programmer interfaces.

"An API is to the programmer what a GUI is to the end-user. The 'P' in AP=
I
stands for "Programmer", not "Program", to highlight the fact that APIs a=
re
used by programmers, who are humans."

http://doc.trolltech.com/qq/qq13-apis.html
--=20
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Bob Bell wrote:

> "Steven T. Hatton" wrote:
>> kuyper@wizard.net wrote:
>>
>> > "Steven T. Hatton" wrote:
>> >> Stephen Howe wrote:
>> >>
>> >> >>> And which of these authors told you that the proper way to
>> >> >>> understand an API is to read the header(s) by which it is
>> >> >>> implemented?
>> >> >>
>> >> >> Bjarne Stroustrup
>> >> >
>> >> > Did he? Where? Please quote a paragraph and page number. Thank you.
>> >>
>> >> Read the book.
>> >
>> > I have. Didn't see it. If it was there, and I missed it, and you claim
>> > to have seen it, it helps your case enormously if you can tell me
>> > where.
>> >
>> > When you make a claim about a book that is in conflict with my memory
>> > of that book, I'm entitled to assume that your refusal to provide a
>> > more specific citation is because you can't provide one.
>>
>> It's pervasive
>
> I might have missed a line or two, but if it were pervasive, I'm pretty
> sure I would remember it. Bjarne mentions header files in very specific
> places, and in none of them do I recall a recommendation that users
> read them to understand the APIs they contain.

Page 634

> Among my assumptions is that code is more appropriate for
> human-to-computer communication than human-to-human; the human-to-human
> thing must be a secondary consideration, since there are already
> natural languages that fit this bill. It's therefore no surprise that
> API documentation tends to be written in natural languages. Further, if
> code were an appropriate domain for human-to-human communication, there
> would be no need for comments.

I have literally thousands of libraries on my harddrive written in C, C++,
elisp, clisp, Java, C# and who knows what else. Almost all of these provide
the API specification as part of the source code.  Often the souce code is
effective API documentation without comments.

>> For an exact citation quoted from the text of TC++PL(SE) please review
>> this thread from the beginning.
>
> I (and others, it seems) have examined your citations and found them to
> be ambiguous at best. If you're so sure you're right, please post
> unambiguous citations.

QED
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
.
> > ... I don't think it's appropriate
> > to require it to be written to be understandable to all users.
>
> I never suggested that it should be.

And I went out of my way to make it clear that I wasn't suggesting that
you had made any such suggestion:

> > I'm not suggesting that you've asked for such a change;

.
> > Note: examination of the contents of the header is not covered by the
> > "observable behavior" rule.
>
> And what has that to do with the subject at hand?

It forestalls a possible counter-argument you might have chosen to use,
but didn't. If you don't see the connection, that means you're
interpreting that part of the standard correctly; but I've argued
before with people who didn't understand that point..

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
.
> > particular implementation. You can't create a non-committal standard
> > header file that leaves that typedef unspecified and have it actually
> > be compileable.
>
> I never said these should be compilable.

I agree, but compileability is about the only advantage I can see to
collecting them together into seperate files. You haven't made it clear
how there's any other advantage to such an arrangement, though you've
repeatedly claimed that there is.

.
> ...  I have found the
> result very useful.

This implies that you've already put these files together. If so, then
you should post them somewhere, so other people can judge the
usefulness of presenting that information in that format.

.
> > I can understand not understanding what a function object is; I've had
> > the fun of trying to explain that to several C++ newbies, and for some
> > of them it's a very tricky concept. But you won't resolve that
> > confusion by looking at a declaration for mem_fun().
>
> I'm not sure what point you are trying to make.

I'm saying that it's easy for me to understand having trouble
understanding function objects, but that I find it difficult to
understand having trouble distinguishing between a function and it's
return type.


> ... I have provided other examples
> of where the files I have created based on the content of the Standard have
> been useful to me.  These files are useful to me.  You are not in a
> position to assess that assertion.  The best you can do is consider whether
> they would be useful to others, and whether that usefulness would add
> sufficient value to the Standard document to justify their inclusion.

And my judgement is that I don't think they would be; that judgement is
based in part upon my feeling that these files are not a significant
improvement over the current standard, not even for the examples you've
given.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Bob Bell wrote:
.
> > I might have missed a line or two, but if it were pervasive, I'm pretty
> > sure I would remember it. Bjarne mentions header files in very specific
> > places, and in none of them do I recall a recommendation that users
> > read them to understand the APIs they contain.
>
> Page 634

I have the third edition, not the second one, so your page number is
useless citation for me. Could you please quote some actual text, and
give a section number and a section title?

While I would certainly recommend that every C++ programmer should own
a copy of TSC++PL, you shouldn't assume that everyone actually does.
Quoting actual text as part of your citation helps include people in
the discussion who either don't have a copy of the book, or have their
copy in an inconvenient location (such as 3000 miles away). Even for
people who do have the book, it's helpful to know which of the hundreds
of words that appear on any one page are the words that you're actually
referring to.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> David Abrahams wrote:
>
> > hattons@globalsymmetry.com ("Steven T. Hatton") writes:
.
> >> And they must faithfully follow the declarations in the C++ Standard if
> >> they are to be compliant.
> >
> > Actually, no.  They just have to be indistinguishable from the POV of
> > a correct, portable program.  There lots of well-known ways to have
> > the declarations differ substantially.  For one trivial example, an
> > implmentation can add parameters to any (member) function or class
> > template as long as the parameters have default values.
> >
>
> And that implementation would behave differently when presented with
> conforming C++ code?  I don't believe there are a significant number of
> places where the suggested representative files would require
> qualification.  I am aware of the statement in the standard you are
> referring to.  I agree, it's trivial.

It might behave differently, so long as the resulting behavior
continues to conform to the standard. For instance, the standard
deliberatly leaves unspecified the order of various operations with
respect to each other; sequence points impose only a partial ordering,
not a complete ordering. The difference in the header declarations
might change the way the implementation resolves the ordering of those
operations.

As another example, in many ways the specification of standard library
template classes leaves it unspecified whether a given operator
overload is a member function or an friend function, a distinction that
does sometimes effect the way a given piece of code will be translated
and executed.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
>
> > "Steven T. Hatton" wrote:
.
> > When you make a claim about a book that is in conflict with my memory
> > of that book, I'm entitled to assume that your refusal to provide a
> > more specific citation is because you can't provide one.
>
> It's pervasive ...

If the idea that "the proper way to understand an API is to read the
header(s) by which it is implemented" is in fact pervasive in
TC++PL(SE), then it shouldn't be difficult to provide a specific
citation from that book which reflects that point of view. Ideally,
that citation would take the form of a direct quote, accompanied by the
number and title of the section being quoted. That will make it easier
for those of us using a more modern edition than yours to find the
text, despite the changes in page numbering.

> ... and relies on certain assumptions about programming which I
> hold to be axiomatic.  Among these assumptions is that the primary reason
> for creating programming languages is to facilitate human-to-human (and
> that can be understood selfreferentially) communication while at the same
> time preparing a set of instructions to be automatically executed by a
> computer.

In my experience, most claims that something is axiomatically true
reflect the fact that the person who is asserting it can't find
supporting arguments, and this is usually because the "axiom" is in
fact false. Your claim is no exception.

While facilitating human-to-human communication is a desireable goal
for a computer language, my understanding is that for most of the
languages ever designed, it has (correctly) been at best a secondary
goal, unambiguously inferior to the other goal you mention:
"facilitat[ing] ... the preparation of a set of instructions to be
automatically executed by a computer".

In general, it's not possible to simultaneously maximize two different
functions of multiple variables (though there's lots of specific
counter-examples with particular pairs of functions). As a result, it's
generally an error to assign a single priority to the meeting of two
different goals; it provides no basis for deciding between them when
the goals conflict (as they almost inevitably will). Choosing such a
specification as an axiom shows poor judgement.

There have been particular computer languages where facilitating
human-to-human communication was given a very high priority. However,
asserting that priority as an axiom is incompatible with the fact that
there are a great many programming languages where it was given a lower
priority. In real life, the amount of priority to be given to that goal
is a judgement call, not an axiom.

> For an exact citation quoted from the text of TC++PL(SE) please review this
> thread from the beginning.

I've reviewed the entire thread, from the beginning. I didn't recognise
anything you've written as constituting a citation of specific text
from TC++PL(SE) which supports your claim. Could you be more specific?
At a minimum, please identify which of your messages contains that
citation. Better yet, please repeat the citation. And, as I suggested
above, it's much more effective if your citation consists of an actual
quote from the book, accompanied by a section number an section title.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> I know what you mean. I remember a mistake I made when I was new to the
> C++ standard, by assuming that "aggregate type" was ordinary English,
> rather than a specific piece of jargon defined by the standard. As a
> result, I missed a rather important piece of specification that applies
> to POD types, because that specification was connected to POD types
> only through the use of the term "aggregate type". I searched for all
> occurances in the standard of "POD", but didn't think to search for
> "aggregate" as well.

If you google comp.lang.c++ for this subject header:
"Should pointer members be zero initialized by default"
you can find where I made a very similar mistake.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

In article <1120591585.133735.42420@g47g2000cwa.googlegroups.com>, Bob
Bell <belvis@pacbell.net> writes
>I might have missed a line or two, but if it were pervasive, I'm pretty
>sure I would remember it. Bjarne mentions header files in very specific
>places, and in none of them do I recall a recommendation that users
>read them to understand the APIs they contain.

This may just be me, but I have always kept a clear distinction in my
mind between Standard headers and header files. The former meet the
requirements of the c++ Standard in that they make certain names
available for use. How they achieve that is entirely up to the
implementation. Header files are a particular kind of user written
source code files. They often do effectively provide an interface. The
specific characteristic of a header file is that it is source code that
may be included in multiple TUs without breaching the ODR.

C++ headers may be implemented as header files but there is no
requirement that they be provided that way and any code that assumes
they will be is non-portable.


--
Francis Glassborow      ACCU
Author of 'You Can Do It!' see http://www.spellen.org/youcandoit
For project ideas and contributions: http://www.spellen.org/youcandoit/projects

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> kuyper@wizard.net wrote:
> .
>> > particular implementation. You can't create a non-committal standard
>> > header file that leaves that typedef unspecified and have it actually
>> > be compileable.
>>
>> I never said these should be compilable.
>
> I agree, but compileability is about the only advantage I can see to
> collecting them together into seperate files. You haven't made it clear
> how there's any other advantage to such an arrangement, though you've
> repeatedly claimed that there is.
>
> .
>> ...  I have found the
>> result very useful.
>
> This implies that you've already put these files together. If so, then
> you should post them somewhere, so other people can judge the
> usefulness of presenting that information in that format.

Let me understand this.  You want to actually _see_ these files in order to
know if seeing these files would be helpful in understanding how they might
be useful.  If I'm not mistaken that means that simply reading the Standard
will not communicate exactly the same essence as actually seeing these
files.  I believe you've made my point for me.

Here is one example.  I don't know if it is either correct or complete.  I
find this form of presentation useful.  It may actually be better to leave
out the kinds of comments we find in the excerpts from the Standard Headers
included in TC++PL.  When you can look at this and feel confident that you
know what it says, then you *know* <iosfwd>

#ifndef IOS_HH
#define IOS_HH
#include <iosfwd>
namespace std {


  typedef OFF_T streamoff;
  typedef SZ_T streamsize;
  template <class stateT> class fpos;
  class ios_base;
  template <class charT, class traits = char_traits<charT> >
  class basic_ios;
  // 27.4.5, manipulators:
  ios_base& boolalpha (ios_base& str);
  ios_base& noboolalpha(ios_base& str);
  ios_base& showbase (ios_base& str);
  ios_base& noshowbase (ios_base& str);
  ios_base& showpoint (ios_base& str);
  ios_base& noshowpoint(ios_base& str);
  ios_base& showpos (ios_base& str);
  ios_base& noshowpos (ios_base& str);
  ios_base& skipws (ios_base& str);
  ios_base& noskipws (ios_base& str);
  ios_base& uppercase (ios_base& str);
  ios_base& nouppercase(ios_base& str);
  ios_base& unitbuf (ios_base& str);
  ios_base& nounitbuf (ios_base& str);
  // 27.4.5.2 adjustfield:
  ios_base& internal (ios_base& str);
  ios_base& left (ios_base& str);
  ios_base& right (ios_base& str);
  // 27.4.5.3 basefield:
  ios_base& dec (ios_base& str);
  ios_base& hex (ios_base& str);
  ios_base& oct (ios_base& str);
  // 27.4.5.4 floatfield:
  ios_base& fixed (ios_base& str);
  ios_base& scientific (ios_base& str);

  class ios_base {
  public:
    class failure;
    typedef T1 fmtflags;
    static const fmtflags boolalpha;
    static const fmtflags dec;
    static const fmtflags fixed;
    static const fmtflags hex;
    static const fmtflags internal;
    static const fmtflags left;
    static const fmtflags oct;
    static const fmtflags right;
    static const fmtflags scientific;
    static const fmtflags showbase;
    static const fmtflags showpoint;
    static const fmtflags showpos;
    static const fmtflags skipws;
    static const fmtflags unitbuf;
    static const fmtflags uppercase;
    static const fmtflags adjustfield;
    static const fmtflags basefield;
    static const fmtflags floatfield;
    typedef T2 iostate;
    static const iostate badbit;
    static const iostate eofbit;
    static const iostate failbit;
    static const iostate goodbit;
    typedef T3 openmode;
    static const openmode app;
    static const openmode ate;
    static const openmode binary;
    static const openmode in;
    static const openmode out;
    static const openmode trunc;
    typedef T4 seekdir;
    static const seekdir beg;
    static const seekdir cur;
    static const seekdir end;

    class Init;
    // 27.4.2.2 fmtflags state:
    fmtflags flags() const;
    fmtflags flags(fmtflags fmtfl);
    fmtflags setf(fmtflags fmtfl);
    fmtflags setf(fmtflags fmtfl, fmtflags mask);
    void unsetf(fmtflags mask);
    streamsize precision() const;
    streamsize precision(streamsize prec);
    streamsize width() const;
    streamsize width(streamsize wide);
    // 27.4.2.3 locales:
    locale imbue(const locale& loc);
    locale getloc() const;
    // 27.4.2.5 storage:
    static int xalloc();
    long& iword(int index);
    void*& pword(int index);
    // destructor
    virtual ?ios_base();
    // 27.4.2.6 callbacks;
    enum event { erase_event, imbue_event, copyfmt_event };
    typedef void (*event_callback)(event, ios_base&, int index);
    void register_callback(event_callback fn, int index);
    static bool sync_with_stdio(bool sync = true);
  protected:
    ios_base();
  private:
    // static int index; exposition only
    // long* iarray; exposition only
    // void** parray; exposition only
  private:
    ios_base(const ios_base&);
    ios_base& operator=(const ios_base&);
  };


  class ios_base::failure : public exception {
  public:
    explicit failure(const string& msg);
    virtual ?failure();
    virtual const char* what() const throw();
  };

  class ios_base::Init {
  public:
    Init();
    ?Init();
  private:
    // static int init_cnt; exposition only
  };

  template <class stateT> class fpos {
  public:
    // 27.4.3.1 Members
    stateT state() const;
    void state(stateT);
    private;
    // stateT st; exposition only
  };


  template <class charT, class traits = char_traits<charT> >
  class basic_ios : public ios_base {
  public:
    // Types:
    typedef charT char_type;
    typedef typename traits::int_type int_type;
    typedef typename traits::pos_type pos_type;
    typedef typename traits::off_type off_type;
    typedef traits traits_type;

    operator void*() const;
    bool operator!() const;
    iostate rdstate() const;
    void clear(iostate state = goodbit);
    void setstate(iostate state);
    bool good() const;
    bool eof() const;
    bool fail() const;
    bool bad() const;
    iostate exceptions() const;
    void exceptions(iostate except);
    // 27.4.4.1 Constructor/destructor:
    explicit basic_ios(basic_streambuf<charT,traits>* sb);
    virtual ?basic_ios();
    // 27.4.4.2 Members:
    basic_ostream<charT,traits>* tie() const;
    basic_ostream<charT,traits>* tie(basic_ostream<charT,traits>* tiestr);
    basic_streambuf<charT,traits>* rdbuf() const;
    basic_streambuf<charT,traits>* rdbuf(basic_streambuf<charT,traits>* sb);
    basic_ios& copyfmt(const basic_ios& rhs);
    char_type fill() const;
    char_type fill(char_type ch);
    // 27.4.2.3 locales:
    locale imbue(const locale& loc);
    char narrow(char_type c, char dfault) const;
    char_type widen(char c) const;
  protected:
    basic_ios();
    void init(basic_streambuf<charT,traits>* sb);
  private:
    basic_ios(const basic_ios& ); // not defined
    basic_ios& operator=(const basic_ios&); // not defined
  };

}

#endif

On a different but related subject:

One other point I have not yet mentioned about the entire concept of headers
which I find frustrating.  The reverse mapping can be difficult to track.
If there is an identifier in some source code I'm reading, and several
#includes without relative paths, e.g., <filename.hh> vs
<libname/filename.hh>, finding the actual declaration can be a challenge.
grep -r identifier * is helpful if I know about where to start.

A related difficulty arises when I know the identifier, but not the name of
the header (standard or otherwise).  For a modest example, std::boolalpha.
Ok, I know it's in <somethingmanip> <iosmanip>? Whoops, won't compile!
<iomanip>.  I'm sure this seems trivial, but it represents a bigger problem
of locating resources quickely.


--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

David Abrahams wrote:

> Actually, no.  They just have to be indistinguishable from the POV of
> a correct, portable program.  There lots of well-known ways to have
> the declarations differ substantially.  For one trivial example, an
> implmentation can add parameters to any (member) function or class
> template as long as the parameters have default values.

I don't doubt you're aware of this, but to nit pick: this doesn't
actually follow for "any (member) function", only for non-virtual member
functions. This is captured in 17.4.4.4.

As for templates, adding more defaulted template parameters presents a
subtle problem that is handled differently by implementations as well;

   http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_closed.html#150

The general point - indistinguishability from the POV of a correct
program - is not contested of course.

~Marc.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") writes:

> David Abrahams wrote:
>
>> hattons@globalsymmetry.com ("Steven T. Hatton") writes:
>>
>>>>> I did not write implementation.  I wrote "as a means of _declaring_ the
>>>>> API to the Standard Library".
>>>>
>>>> That is part of the implementation. Declarations of types and
>>>> functions are a part of the implementation.
>>>
>>> And they must faithfully follow the declarations in the C++ Standard if
>>> they are to be compliant.
>>
>> Actually, no.  They just have to be indistinguishable from the POV of
>> a correct, portable program.  There lots of well-known ways to have
>> the declarations differ substantially.  For one trivial example, an
>> implmentation can add parameters to any (member) function or class
>> template as long as the parameters have default values.
>>
>
> And that implementation would behave differently when presented with
> conforming C++ code?

No, that is my point.

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> kuyper@wizard.net wrote:
>>
>> > "Steven T. Hatton" wrote:
> .
>> > When you make a claim about a book that is in conflict with my memory
>> > of that book, I'm entitled to assume that your refusal to provide a
>> > more specific citation is because you can't provide one.
>>
>> It's pervasive ...
>
> If the idea that "the proper way to understand an API is to read the
> header(s) by which it is implemented" is in fact pervasive in
> TC++PL(SE), then it shouldn't be difficult to provide a specific
> citation from that book which reflects that point of view. Ideally,
> that citation would take the form of a direct quote, accompanied by the
> number and title of the section being quoted. That will make it easier
> for those of us using a more modern edition than yours to find the
> text, despite the changes in page numbering.

I provided a sufficient quote in the first post in this thread.

>> ... and relies on certain assumptions about programming which I
>> hold to be axiomatic.  Among these assumptions is that the primary reason
>> for creating programming languages is to facilitate human-to-human (and
>> that can be understood selfreferentially) communication while at the same
>> time preparing a set of instructions to be automatically executed by a
>> computer.
>
> In my experience, most claims that something is axiomatically true
> reflect the fact that the person who is asserting it can't find
> supporting arguments, and this is usually because the "axiom" is in
> fact false. Your claim is no exception.
>
> While facilitating human-to-human communication is a desireable goal
> for a computer language, my understanding is that for most of the
> languages ever designed, it has (correctly) been at best a secondary
> goal, unambiguously inferior to the other goal you mention:
> "facilitat[ing] ... the preparation of a set of instructions to be
> automatically executed by a computer".

You will note that I also stated that the human to human communication
includes selfreferential communication.


--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> Bob Bell wrote:
> .
>> > I might have missed a line or two, but if it were pervasive, I'm pretty
>> > sure I would remember it. Bjarne mentions header files in very specific
>> > places, and in none of them do I recall a recommendation that users
>> > read them to understand the APIs they contain.
>>
>> Page 634
>
> I have the third edition, not the second one, so your page number is
> useless citation for me. Could you please quote some actual text, and
> give a section number and a section title?
>
> While I would certainly recommend that every C++ programmer should own
> a copy of TSC++PL, you shouldn't assume that everyone actually does.
> Quoting actual text as part of your citation helps include people in
> the discussion who either don't have a copy of the book, or have their
> copy in an inconvenient location (such as 3000 miles away). Even for
> people who do have the book, it's helpful to know which of the hundreds
> of words that appear on any one page are the words that you're actually
> referring to.

Almost the entire page is an excerpt from a representative <iomanip>.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

In article <R8-dncP5m9EoYVbfRVn-gw@speakeasy.net>, Steven T. Hatton
<hattons@globalsymmetry.com> writes
>Almost the entire page is an excerpt from a representative <iomanip>.

So? All that shows is that BS selected a part of a specific version of a
specific header file to leverage. It says nothing about the general
principle. In addition, without a time machine the 2nd edition could not
quote any part of any implementation of <iomanip>. The version of C++
covered in the 2nd edition was substantially different to what was
eventually the C++ Standard. Some of the biggest differences are in the
Library as a result of a substantial injection of templates.

>

--
Francis Glassborow      ACCU
Author of 'You Can Do It!' see http://www.spellen.org/youcandoit
For project ideas and contributions: http://www.spellen.org/youcandoit/projects

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

""Steven T. Hatton"" <hattons@globalsymmetry.com> wrote in message
news:JbOdnfkHuKdYBlbfRVn-qw@speakeasy.net...

> Here is one example.  I don't know if it is either correct or complete.  I
> find this form of presentation useful.  It may actually be better to leave
> out the kinds of comments we find in the excerpts from the Standard
> Headers
> included in TC++PL.  When you can look at this and feel confident that you
> know what it says, then you *know* <iosfwd>
>
> #ifndef IOS_HH
> #define IOS_HH
> #include <iosfwd>
> namespace std {
>
>
>  typedef OFF_T streamoff;
>  typedef SZ_T streamsize;
>  template <class stateT> class fpos;
>  class ios_base;
>  template <class charT, class traits = char_traits<charT> >
>  class basic_ios;
>  // 27.4.5, manipulators:
>  ios_base& boolalpha (ios_base& str);
>  ios_base& noboolalpha(ios_base& str);
> .....
> #endif

See:

http://www.dinkumware.com/manuals/reader.aspx?b=p/&h=ios.html

> On a different but related subject:
>
> One other point I have not yet mentioned about the entire concept of
> headers
> which I find frustrating.  The reverse mapping can be difficult to track.
> If there is an identifier in some source code I'm reading, and several
> #includes without relative paths, e.g., <filename.hh> vs
> <libname/filename.hh>, finding the actual declaration can be a challenge.
> grep -r identifier * is helpful if I know about where to start.
>
> A related difficulty arises when I know the identifier, but not the name
> of
> the header (standard or otherwise).  For a modest example, std::boolalpha.
> Ok, I know it's in <somethingmanip> <iosmanip>? Whoops, won't compile!
> <iomanip>.  I'm sure this seems trivial, but it represents a bigger
> problem
> of locating resources quickely.

See:

http://www.dinkumware.com/manuals/reader.aspx?b=p/&h=_index.html

P.J. Plauger
Dinkumware, Ltd.
http://www.dinkumware.com


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Francis Glassborow wrote:

> In article <R8-dncP5m9EoYVbfRVn-gw@speakeasy.net>, Steven T. Hatton
> <hattons@globalsymmetry.com> writes
>>Almost the entire page is an excerpt from a representative <iomanip>.
>
> So? All that shows is that BS selected a part of a specific version of a
> specific header file to leverage. It says nothing about the general
> principle. In addition, without a time machine the 2nd edition could not
> quote any part of any implementation of <iomanip>. The version of C++
> covered in the 2nd edition was substantially different to what was
> eventually the C++ Standard. Some of the biggest differences are in the
> Library as a result of a substantial injection of templates.

TC++PL(SE) = The C++ Programming Language (Special Edition)
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

P.J. Plauger wrote:

> ""Steven T. Hatton"" <hattons@globalsymmetry.com> wrote in message
> news:JbOdnfkHuKdYBlbfRVn-qw@speakeasy.net...
>
>> Here is one example.  I don't know if it is either correct or complete.
>> I
>> find this form of presentation useful.  It may actually be better to
>> leave out the kinds of comments we find in the excerpts from the Standard
>> Headers
>> included in TC++PL.  When you can look at this and feel confident that
>> you know what it says, then you *know* <iosfwd>
>>
>> #ifndef IOS_HH
>> #define IOS_HH
>> #include <iosfwd>
>> namespace std {
>>
>>
>>  typedef OFF_T streamoff;
>>  typedef SZ_T streamsize;
>>  template <class stateT> class fpos;
>>  class ios_base;
>>  template <class charT, class traits = char_traits<charT> >
>>  class basic_ios;
>>  // 27.4.5, manipulators:
>>  ios_base& boolalpha (ios_base& str);
>>  ios_base& noboolalpha(ios_base& str);
>> .....
>> #endif
>
> See:
>
> http://www.dinkumware.com/manuals/reader.aspx?b=p/&h=ios.html

That is very nice documentation.  It's not exactly what I'm talking about.
I'm actually talking about undocumentation.  I don't _want_ documentation
in the files I was talking about.  I may just go ahead and try to user your
documentation to figure out the parts of my header files that I still
haven't sorted out.

>> On a different but related subject:
>>
>> One other point I have not yet mentioned about the entire concept of
>> headers
>> which I find frustrating.  The reverse mapping can be difficult to track.
>> If there is an identifier in some source code I'm reading, and several
>> #includes without relative paths, e.g., <filename.hh> vs
>> <libname/filename.hh>, finding the actual declaration can be a challenge.
>> grep -r identifier * is helpful if I know about where to start.
>>
>> A related difficulty arises when I know the identifier, but not the name
>> of
>> the header (standard or otherwise).  For a modest example,
>> std::boolalpha. Ok, I know it's in <somethingmanip> <iosmanip>? Whoops,
>> won't compile!
>> <iomanip>.  I'm sure this seems trivial, but it represents a bigger
>> problem
>> of locating resources quickely.
>
> See:
>
> http://www.dinkumware.com/manuals/reader.aspx?b=p/&h=_index.html

Again.  That can might come in handy.  I actually generated my own reverse
index into the headers.  But I was really trying to address a more general
problem working with C++ source bases. In comparison to Java and C#, it's
harder to "mine" the code.  The main reasons for this are the lack of
standardization in file extension naming, lack of standardization in
directory structure, the !#$%^ #include mechanism, add #MACROs to that, and
it becomes mind boggling to contemplate a general solution.

> P.J. Plauger
> Dinkumware, Ltd.
> http://www.dinkumware.com
>
>
> ---
> [ comp.std.c++ is moderated.  To submit articles, try just posting with ]
> [ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
> [              --- Please see the FAQ before posting. ---               ]
> [ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
.
> > This implies that you've already put these files together. If so, then
> > you should post them somewhere, so other people can judge the
> > usefulness of presenting that information in that format.
>
> Let me understand this.  You want to actually _see_ these files in order to
> know if seeing these files would be helpful in understanding how they might
> be useful.  If I'm not mistaken that means that simply reading the Standard
> will not communicate exactly the same essence as actually seeing these
> files.  I believe you've made my point for me.

No, the point I'm making is exactly the reverse. I expected that when
you present those files we will find that they communicate exactly the
same essense as reading the Standard, in a less useful format. However,
you claim otherwise. I was asking you to back up that claim by
presenting them so we can check whether or not you're right. Having
looked at your example, the advantages you claim aren't clear to me.
However, others may feel differently.

.
> On a different but related subject:
>
> One other point I have not yet mentioned about the entire concept of headers
> which I find frustrating.  The reverse mapping can be difficult to track.
> If there is an identifier in some source code I'm reading, and several
> #includes without relative paths, e.g., <filename.hh> vs
> <libname/filename.hh>, finding the actual declaration can be a challenge.
> grep -r identifier * is helpful if I know about where to start.

On the compilers I use, the -E option creates a preprocessed output
file with embedded #line directives. The result is excessively long
(though removing all blank lines helps considerably), but despite that
I've found it quite helpful in locating where an identifier is
defined/declared (except for macros, unfortunately). I understand that
most modern GUI software development tools provide the same information
(even for macros) by a simpler method, but unfortunately it's hard to
use those tools in our development environment.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

> I have literally thousands of libraries on my harddrive written in C, C++,
> elisp, clisp, Java, C# and who knows what else. Almost all of these
> provide
> the API specification as part of the source code.  Often the souce code is
> effective API documentation without comments.

Sorry, I think this is nonsense. I have Bjarne's Special Edition.

You say "Often the souce code is effective API documentation without
comments".
Really? How "often" is that?  Consider section "21.4.1 Format State" on page
625.

NOTE: For the benefit of others here without the book, it has

class ios_base {
public:

    typedef implementation_defined1 fmtflags;
    static const fmtflags
        skipws,
        left,
        right,
        internal,
        boolalpha,
        dec,
        hex,
        oct,
        scientific,
        fixed,
        showbase,
        showpoint,
        showpos,
        uppercase,
        adjustfield,
        basefield,
        floatfield,
        unitbuf;

    fmtflags flags() const;
    fmtflags flags(fmtflags f);
    fmtflags setf(fmtflags f) { return flags(flags() | f); }
    fmtflags setf(fmtflags f, fmtflags mask) { return flags((flags() &
~mask) | (f & mask)); }
    void unsetf(fmtflags mask) { return flags(flags() & ~mask); }
};

NOTE ALSO: I have stripped all Bjarnes // comments as Steven claims, "Often
the souce code is effective API documentation without comments".

Now given just the above, from the header files alone, _WITHOUT_ reading any
additional documentation on iostream formatting

(i) How would you switch formatting to scientific-format for cout?
(ii) And how would you switch formatting after that to fixed-format for
cout?

Please answer these questions based on the above extract.

You see it is Bjarnes notes in section "21.4.3 Floating-Point Output" makes
it dead easy but you are claiming that I can gain the same knowledge from
the above API. I say otherwise. Nowhere from above do I know which of the
setf()'s I should call. I can show this to a competent and bright C++
programmer at work that I know is unfamilar with iostream float formatting
and see if he gets it wrong.

Note you said also in reply to Bob Bell:

>>>>>>>>
> BBell: And which of these authors told you that the proper way to
> understand
> BBell: an API is to read the header(s) by which it is implemented?
>
> SHatton: Bjarne Stroustrup
>>>>>>>>

Sorry, I don't see that from "The C++ Programming Language, Special
Edition".

1. I looked up the word "header" in the index at the back. 8 references, 7
page numbers.
Not once does Bjarne recommend to read the header file.

2. I looked up the word "documentation" in the index at the back. 1
references, 2 pages.

About the best that can be said is under section "23.5.1 Reuse" where Bjarne
says

>>>>>>>>>>>>>>>>>>
Reuse is primarily a social phenomenon. I can use someone else's software
provided that:
[1] It works: to be reusable, software must first be usable.
[2] It is comprehensible: program structure, comments, documentation, and
tutorial material are important.
:
>>>>>>>>>>>>>>>>>>

I guess you can stretch "program structure" to mean header files but that is
hardly an explicit recommendation. That is quite a jump.
And in the same line, Bjarne is recommending comments, documentation and
tutorials.

3. The block of iostream definitions you quoted happens to be from a chapter
under the section "Part III: The Standard Library".
Looking at other chapters in this section, we see similar blocks of
definitions from <algorithm>, <list>, <vector> etc.
So it makes sense to look at the start of the section "Part III: The
Standard Library" to see if Bjarne gives any guidelines as to why he is
quoting definitions. I don't find any such thing.

Stephen Howe


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuy...@wizard.net wrote:

> If the idea that "the proper way to understand an API is to read the
> header(s) by which it is implemented" is in fact pervasive in
> TC++PL(SE), then ...

It is not, obviously not, but I *do* recommend that people look at
their headers. Sometimes the headers are incomprehensible, and they
always containe more crud than we'd like to see (more than even the
implementers would like there). However, once a programmer/student has
exhaused the available documentation, it is a good healthy practice to
have a look at the headers (though the file or maybe through an IDE).
They may not be very clear, they may be confusing, but they're there
and one can learn something from them - often they are more easily
accessible than the standard or (my:-) book. I carry those on my
laptop, but not everybody does. Obviously, the standard library headers
are *not* the definition of the standard library. There are often
omissions in a particular set of headers, even more often non-standard
extensions, and the semantics is most often left obscure. However,
after an initial learning period, we can't protect new programmers from
the messy world, and the standard library headers are often worthwhile
reading. Headers is not the first place to look for understanding a
library, but it is a place where it is good to look occationally - or
we might end up with an overly idealized or legalistic view of
programming.

Knowing that we look may also occationally help encourage an
implementer not to make headers more messy than necessary.

  -- Bjarne Stroustrup; http://www.research.att.com/~bs

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:
> I have the third edition, not the second one, so your page number is
> useless citation for me. Could you please quote some actual text, and
> give a section number and a section title?

The first sentence of 17.1.1 says
     "This section lists the common and almost common members of the
      standard containers. For more details, read your standard headers"

Now, the members of a class must all appear together in one place,
because class declarations cannot be reopened. So it's very likely
that you will find all the members collected for you in one place.
Still, that's not the most brilliant recommendation.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Stephen Howe wrote:

>> I have literally thousands of libraries on my harddrive written in C,
>> C++, elisp, clisp, Java, C# and who knows what else. Almost all of these
>> provide
>> the API specification as part of the source code.  Often the souce code
>> is effective API documentation without comments.
>
> Sorry, I think this is nonsense. I have Bjarne's Special Edition.
>
> You say "Often the souce code is effective API documentation without
> comments".
> Really? How "often" is that?  Consider section "21.4.1 Format State" on
> page 625.
>
> NOTE: For the benefit of others here without the book, it has
>
> class ios_base {
> public:
>
>     typedef implementation_defined1 fmtflags;
>     static const fmtflags
>         skipws,
>         left,
>         right,
>         internal,
>         boolalpha,
>         dec,
>         hex,
>         oct,
>         scientific,
>         fixed,
>         showbase,
>         showpoint,
>         showpos,
>         uppercase,
>         adjustfield,
>         basefield,
>         floatfield,
>         unitbuf;
>
>     fmtflags flags() const;
>     fmtflags flags(fmtflags f);
>     fmtflags setf(fmtflags f) { return flags(flags() | f); }
>     fmtflags setf(fmtflags f, fmtflags mask) { return flags((flags() &
> ~mask) | (f & mask)); }
>     void unsetf(fmtflags mask) { return flags(flags() & ~mask); }
> };
>
> NOTE ALSO: I have stripped all Bjarnes // comments as Steven claims,
> "Often the souce code is effective API documentation without comments".
>
> Now given just the above, from the header files alone, _WITHOUT_ reading
> any additional documentation on iostream formatting
>
> (i) How would you switch formatting to scientific-format for cout?
> (ii) And how would you switch formatting after that to fixed-format for
> cout?
>
> Please answer these questions based on the above extract.

What you are demonstrating is a flaw in the interface.  I recently suggested
"wrapping up" this interface in some structs to make it more intuitive.
The interface is ancient, and does not refect many advances in program
design which have taken place since it's creation.

Note also that one of my arguments for creating the representative example
Standard Header Files is so that the interface can be examined in exactly
the light you have presented it in.

I _never_ said comments are not valuable.  I never said documentation is not
valuable.  I never said reading tutorials and text books isn't valuable.
But I stand by my assertion that viewing an API sans comments or other
documentation is an instructive exercise for both the user, and probably
more importantly, the designer.  Your example amplifies that conviction.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

bjarne wrote:
> It is not, obviously not, but I *do* recommend that people look at
> their headers.
>
 In principle, not only the headers but the whole set of source files are
worth to look at.
 It's widely accepted that good code should not depend on implementation
details. Unfortunately, too few authoritative sources recommend to always
inspect at least one implementation (in key details). As a result, people tend
to deliberately ignore all the implementations and use the interfaces in
unnatural ways...
--
         With all respect, Sergey.               http://ders.angen.net/
         mailto : ders at skeptik.net

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Bob Bell wrote:
> > "Steven T. Hatton" wrote:
> >> kuyper@wizard.net wrote:
> >> > "Steven T. Hatton" wrote:
> >> >> Stephen Howe wrote:
> >> >>
> >> >> >>> And which of these authors told you that the proper way to
> >> >> >>> understand an API is to read the header(s) by which it is
> >> >> >>> implemented?
> >> >> >>
> >> >> >> Bjarne Stroustrup
> >> >> >
> >> >> > Did he? Where? Please quote a paragraph and page number. Thank you.
> >> >>
> >> >> Read the book.
> >> >
> >> > I have. Didn't see it. If it was there, and I missed it, and you claim
> >> > to have seen it, it helps your case enormously if you can tell me
> >> > where.
> >> >
> >> > When you make a claim about a book that is in conflict with my memory
> >> > of that book, I'm entitled to assume that your refusal to provide a
> >> > more specific citation is because you can't provide one.
> >>
> >> It's pervasive
> >
> > I might have missed a line or two, but if it were pervasive, I'm pretty
> > sure I would remember it. Bjarne mentions header files in very specific
> > places, and in none of them do I recall a recommendation that users
> > read them to understand the APIs they contain.
>
> Page 634

Thank you; I appreciate the attempt to provide more detailed citations.
However, I fail to see how this page supports the idea that the proper
way to understand an API is to read the header(s) by which it is
implemented.

What I do see on this page is a set of declarations for standard
manipulators which are brought in by #include'ing <iomanip>. I can only
guess that you think this implies that Bjarne is recommending users
actually look into the header file (if any) behind <iomanip>. However,
it is clear that the text on this page is _not_ the text of such a
file, for at least the following reasons:

-- there are no include guards
-- there is no mention of namespace std
-- none of the templates are declared "export", yet their
implementations are not present, nor are any nested #includes which
might contain those implementations
-- there are comments which contain references to relevant sections of
Bjarne's book; surely an actual header file would lack those, unless
the header was part of a standard library implementation written by
Bjarne himself (possible, I suppose, but there's no mention of such an
implementation anywhere in the book, so why suppose it exists?)

I don't see how one can interpret page 634 as supporting the idea that
users should read header files, unless one assumes that the text of 634
is verbatim from a header file (or nearly so), and that one further
assumes Bjarne's purpose in quoting such a header file is to serve as
an example of what users themselves should do.

> > Among my assumptions is that code is more appropriate for
> > human-to-computer communication than human-to-human; the human-to-human
> > thing must be a secondary consideration, since there are already
> > natural languages that fit this bill. It's therefore no surprise that
> > API documentation tends to be written in natural languages. Further, if
> > code were an appropriate domain for human-to-human communication, there
> > would be no need for comments.
>
> I have literally thousands of libraries on my harddrive written in C, C++,
> elisp, clisp, Java, C# and who knows what else. Almost all of these provide
> the API specification as part of the source code.  Often the souce code is
> effective API documentation without comments.

It seems like your belief is that any API documentation that contains
function prototypes, class definitions, or anything else that looks
like code necessarily supports the idea that users should read header
files. If this is indeed your belief, I don't know what else there is
to say. It seems pretty simple: you want to look at header files and
source code to understand an API. Fine; I won't stop you. You even
claim that it helps you understand what's going on better than anything
else. I won't argue with that either; you're the expert on what helps
you learn.

If you want to claim that TC++PL supports this idea, well, I'm afraid I
don't believe you; the evidence thus far has not convinced me.

If you want the C++ standard to contain what amounts to some sort of
example headers, by all means, write them and submit a proposal to the
committee. I'm sure they'll give you a fair evaluation.

Good luck,

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

This is the Internet. Put them up on a website somewhere.

--
 Pedro Lamar   o


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Pete Becker wrote:
> David Abrahams wrote:
>> "Prateek" writes:

>>> IMHO the Standard Library declarations will be clearer to read if
>>> they used template parameter names like In, Out, For, Bi, Ran,
>>> Pred, etc (like in TC++PL) instead of rambling names like
>>> InputIterator, OutputIterator, ForwardIterator,
>>> BidirectionalIterator, RandomAccessIterator, Predicate, etcetera.
>>
>>
>> N my pnion ur pst wd b ezer 2 rd f u used shrthnd lk me.

> <g> But I agree with Prateek in principle: the current names are far
> too long. In our documentation we use InIt, OutIt, etc. Otherwise you
> end up with really long lines, or you have to break declarations up
> into multiple lines, making them harder to read. Not to mention the
> problems they cause when you try to typeset a book.

I guess you wouldn't look too favorably on
RandomAccessTraversalReadableWritableIterator (http://tinyurl.com/7o62d)

Jonathan


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

thoth39 wrote:

> This is the Internet. Put them up on a website somewhere.

I'm sorry to hear that between sun Mircorsystems, IBM, Mircosoft, Oracle,
AT&T, and all the other companies who benefit from the C++ standard that
the cost of maintaining a representative collection of files declaring the
API to one of their most commonly used libraries should be the inhibiting
factor in producing such.

The material in question is copyrighted, and I do not have the authority to
simply reproduce and publish it.

In the past many months since I first started studying C++ in earnest, the
apparent irrationality of the design and use of the C++ Standard Library
Headers has been the most baffling and irksome contradiction I've
encountered.  I don't care to recount the history of my discussions on this
matter, suffice it to say that there is a lot of disagreement about the
purpose and use of these entities.  I side with the school that holds the
opinion that programming languages were created as a means for humans to
communicate with oneanother at the same time we program computers, and that
the Standard Headers are the formal declaration of Standard Library API,
and should be consulted in order to understand that API.

I have been told that, in practice, these Standard Headers cannot be used,
as-is in a real production environment.  They are said to have cyclical
dependencies which preclude their use as they are specified in the
Standard. The person who tells me that with the greatest confidence also
tells me that he has put considerable effort into resolving these inherent
contradcitions.  In my experience, the best way to solve such a problem -
and this is a problem - is to produce the entire body of declarations and
to examine it to locate, identify, isolate and address the (usually few)
self-referential dependencies.

The C++ Standard Library is an impressive body of work representing a
carefully selected, and fairly orthogonal collection of essential building
blocks upon which programmers have built some of the most sophisticated and
useful mechanisms in human history.  There are some inherent restrictions
which C++ faces in continuing to scale beyond the level of complexity it
currently supports.  The relative (in comparison to more "modern"
languages) difficulty in obtaining information about the programming
resources available to the developer is one of these restrictions.  Ideally
such information should be available in the API.

On my bookshelf is a fairly old book (I never finished) which I bought about
a decade ago when I was first inclined to learn C++.  At the time I bought
the book _Mastering_C++_, by Cay Horstmann, it was considered one of the
best single sources for a beginner to use in learning C++.  It is a very
small, and compact book.  Likewise for TC++ARM.  These represent the state
of affairs in C++ when many of the conventions now espoused by authorities
in C++ were established.  One of these conventions which is relevant to the
current topic is the convention of using header files to hold the interface
to a body of code while a corresponding so-called 'source file' holds the
implementation. Before templates became pervasive, that was sound,
relatively easy to follow advice.

Templates have significantly complicated this design approach in so much as
they often require that both interface, and implementation be visible when
they are processed by the compiler.  This complication makes learning C++
more difficult than it would otherwise be.  The studend must now lean the
programming equivalent of "'i' before 'e', except after 'c', or when
sounded as 'a' as in 'neighbor' or 'weigh'" (or is that neighbour?).  The
value of a clear, well designed interface is no less in 2005 than it was in
1991.  It is, however, more difficult to provide. See the discussion in
_C++ Templates, The Complete Guide_, by van de Voorde and Josuttis, chapter
6 for a discussion of this.

I know that the C++ Standard does not require that the Standard Headers be
actual files on a harddrive, but it is noteworthy the Nicolai Josuttis uses
the term "header files" in TC++SL when discussin the Standard Headers.
Clearly, he thinks in terms of actual header files, as do many C++
programmers.  If the C++ Standard Committee cannot produce the Standard
Headers in the form of C++ source code as a means of declaring the API to
the Standard Library, how can they, or anybody, reasonably expect that
others should produce such interfaces for their libraries?
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:
> the Standard Headers are the formal declaration of Standard Library API,
> and should be consulted in order to understand that API.

APIs are documented, and the documentation should be consulted
to determine their proper use. Header files are part of the
implementation and contain things which are necessary for that.
There should be no expectation that the implementation serves
as the documentation.

The Standard documents the API, or at least it should, to a
sufficient extent such that implementors can create a conforming
version without ambiguity. It is, or should be, complete and
correct, but there should be no expectation that the Standard is
a tutorial for the API or for any aspect of the language. Tutorials
exist in the form of books and FAQs, and those should be consulted
for learning the language.

> I have been told that, in practice, these Standard Headers cannot be used,
> as-is in a real production environment.

These so-called "Standard Headers" cannot be used because they do not
exist. The Standard does not specify their complete contents. Every
implementation supplies its own, correct for that implementation.

 > One of these conventions which is relevant to the
> current topic is the convention of using header files to hold the interface
> to a body of code while a corresponding so-called 'source file' holds the
> implementation. Before templates became pervasive, that was sound,
> relatively easy to follow advice.

Header files contain sufficient code so that the types and functions
they declare can be used by the compilation units which include them.
Source files contain the implementations which are not relevant to the
users of those types and functions. This is as true for templates as
for non-templates, given that we now have compilers with which implement
'export'. There should be no expectation that any of these files serve
as documentation for the things they contain.

> This complication makes learning C++ more difficult than it would otherwise be.

There should be no expectation that one can learn C++ from examining
implementation files, unless those have been carefully written with
pedagogy in mind.

>  If the C++ Standard Committee cannot produce the Standard
> Headers in the form of C++ source code as a means of declaring the API to
> the Standard Library, how can they, or anybody, reasonably expect that
> others should produce such interfaces for their libraries?

The committee never had the intention of producing an implementation of C++.
It exists to specify the language, not implement it. It will no more produce
a library implementation than it would produce any other part of the compiler.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> thoth39 wrote:
>
> > This is the Internet. Put them up on a website somewhere.
>
> I'm sorry to hear that between sun Mircorsystems, IBM, Mircosoft, Oracle,
> AT&T, and all the other companies who benefit from the C++ standard that
> the cost of maintaining a representative collection of files declaring the
> API to one of their most commonly used libraries should be the inhibiting
> factor in producing such.

Sun Microsystems, IBM, Microsoft, Oracle, AT&T and all the other
companies you're thinking of haven't called this a problem, and haven't
volunteered to fix it. Are they supposed to do it because _you_ say so?
_I_ don't think you've identified a problem here, so should _I_ have to
fix it?

It's amazing that you've identified what you claim is a very serious
problem, but you are willing to put more energy into explaining why
someone else should fix it than into trying to fix it yourself. Given
this dichotomy between what you say ("it's a serious problem") and what
you do (nothing), why should anyone else take the problem seriously?
This is not a rhetorical question; I am honestly curious how you
resolve this.

I would think that, at the very least, you would want someone who is
motivated to fix the problem. Someone who really believes there is a
real problem, and who understands it so well that they can identify a
real solution. This discounts me, for example; since I don't understand
why what you describe is a problem, I'm not sure what a solution would
look like.

So far, only one person seems to fit this description, and I'm replying
to his post.

> The material in question is copyrighted, and I do not have the authority to
> simply reproduce and publish it.

Funny, I think that objection applies to everyone else you've decided
should fix this.

> In the past many months since I first started studying C++ in earnest, the
> apparent irrationality of the design and use of the C++ Standard Library
> Headers has been the most baffling and irksome contradiction I've
> encountered.  I don't care to recount the history of my discussions on this
> matter, suffice it to say that there is a lot of disagreement about the
> purpose and use of these entities.  I side with the school that holds the
> opinion that programming languages were created as a means for humans to
> communicate with oneanother at the same time we program computers, and that
> the Standard Headers are the formal declaration of Standard Library API,
> and should be consulted in order to understand that API.

If you're used to working this way (i.e., consulting header files to
understand an API), then you have my sympathies. Perhaps this is the
problem you should be solving instead.

> I have been told that, in practice, these Standard Headers cannot be used,
> as-is in a real production environment.

You've been lied to. I use them, as-is, in a real production
environment every day.

> They are said to have cyclical
> dependencies which preclude their use as they are specified in the
> Standard. The person who tells me that with the greatest confidence also
> tells me that he has put considerable effort into resolving these inherent
> contradcitions.  In my experience, the best way to solve such a problem -
> and this is a problem - is to produce the entire body of declarations and
> to examine it to locate, identify, isolate and address the (usually few)
> self-referential dependencies.
>
> The C++ Standard Library is an impressive body of work representing a
> carefully selected, and fairly orthogonal collection of essential building
> blocks upon which programmers have built some of the most sophisticated and
> useful mechanisms in human history.  There are some inherent restrictions
> which C++ faces in continuing to scale beyond the level of complexity it
> currently supports.  The relative (in comparison to more "modern"
> languages) difficulty in obtaining information about the programming
> resources available to the developer is one of these restrictions.  Ideally
> such information should be available in the API.

You seem to equate "API" with "header files", which is the source of
all of your problems in this area.

Ideally, such information should be available in a library's
_documentation_, the clarity of which is not hampered by having to be a
compilable, executable implementation of the API.

> On my bookshelf is a fairly old book (I never finished) which I bought about
> a decade ago when I was first inclined to learn C++.  At the time I bought
> the book _Mastering_C++_, by Cay Horstmann, it was considered one of the
> best single sources for a beginner to use in learning C++.  It is a very
> small, and compact book.  Likewise for TC++ARM.  These represent the state
> of affairs in C++ when many of the conventions now espoused by authorities
> in C++ were established.  One of these conventions which is relevant to the
> current topic is the convention of using header files to hold the interface
> to a body of code while a corresponding so-called 'source file' holds the
> implementation. Before templates became pervasive, that was sound,
> relatively easy to follow advice.

And which of these authors told you that the proper way to understand
an API is to read the header(s) by which it is implemented?

> Templates have significantly complicated this design approach in so much as
> they often require that both interface, and implementation be visible when
> they are processed by the compiler.  This complication makes learning C++
> more difficult than it would otherwise be.  The studend must now lean the
> programming equivalent of "'i' before 'e', except after 'c', or when
> sounded as 'a' as in 'neighbor' or 'weigh'" (or is that neighbour?).  The
> value of a clear, well designed interface is no less in 2005 than it was in
> 1991.  It is, however, more difficult to provide. See the discussion in
> _C++ Templates, The Complete Guide_, by van de Voorde and Josuttis, chapter
> 6 for a discussion of this.

I don't see how templates make header files any less suitable for
serving as documentation, since they were unsuitable to begin with. In
any case, I don't have my copy of C++ Templates handy, so I'll have to
look this up when I get to work.

> I know that the C++ Standard does not require that the Standard Headers be
> actual files on a harddrive, but it is noteworthy the Nicolai Josuttis uses
> the term "header files" in TC++SL when discussin the Standard Headers.
> Clearly, he thinks in terms of actual header files, as do many C++
> programmers.  If the C++ Standard Committee cannot produce the Standard
> Headers in the form of C++ source code as a means of declaring the API to
> the Standard Library, how can they, or anybody, reasonably expect that
> others should produce such interfaces for their libraries?

If it is unreasonable to expect anyone to produce such interfaces for
their libraries (as you seem to be implying), how do you explain the
various standard library implementations that are available?

It sounds to me like you've become very confused between an API and a
set of header files that implement the API. You sound like you want to
turn to the headers as the first, definitive step in understanding the
API; perhaps you would be better off if, like me, you turned to header
files as a last resort, when all other attempts have been made. One
side benefit of this approach is that, if you repeatedly find yourself
at that last resort of consulting the headers, then you will have
acquired pretty good evidence that the library in question should
probably be avoided.

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Hyman Rosen wrote:

> Steven T. Hatton wrote:
>> the Standard Headers are the formal declaration of Standard Library API,
>> and should be consulted in order to understand that API.
>
> APIs are documented, and the documentation should be consulted
> to determine their proper use. Header files are part of the
> implementation and contain things which are necessary for that.
> There should be no expectation that the implementation serves
> as the documentation.

This is completely inconsistent with virtually everything I have ever read
on program design.  In particular it is inconsistent with what is written
in TC++PL(SE) in the sections I've already cited.  It is also contrary to
my personal experience.

> The Standard documents the API, or at least it should, to a
> sufficient extent such that implementors can create a conforming
> version without ambiguity. It is, or should be, complete and
> correct, but there should be no expectation that the Standard is
> a tutorial for the API or for any aspect of the language. Tutorials
> exist in the form of books and FAQs, and those should be consulted
> for learning the language.

There is a reasonable expectation that the Standad should be accessible as a
reference to the language.  Being able to view the entire API in the form
of class (template) definitions and function declarations cannot be
substituted by providing books about using it. This is a major reason for
having such features as introspection which are core to both Java and C#.
You can query a library and have it programmatically provide its public
interface, or in some cases even more.  That feature is one of the biggest
reason Java is easier to learn than C++.

>> I have been told that, in practice, these Standard Headers cannot be
>> used, as-is in a real production environment.
>
> These so-called "Standard Headers" cannot be used because they do not
> exist. The Standard does not specify their complete contents. Every
> implementation supplies its own, correct for that implementation.

Please review the previous conversation on this matter.  The meaning of my
comments should then be clear to you.

>  > One of these conventions which is relevant to the
>> current topic is the convention of using header files to hold the
>> interface to a body of code while a corresponding so-called 'source file'
>> holds the implementation. Before templates became pervasive, that was
>> sound, relatively easy to follow advice.
>
> Header files contain sufficient code so that the types and functions
> they declare can be used by the compilation units which include them.
> Source files contain the implementations which are not relevant to the
> users of those types and functions. This is as true for templates as
> for non-templates, given that we now have compilers with which implement
> 'export'. There should be no expectation that any of these files serve
> as documentation for the things they contain.

That is your opinion.  In my opinion, you are describing a very bad way of
providing an API.

>> This complication makes learning C++ more difficult than it would
>> otherwise be.
>
> There should be no expectation that one can learn C++ from examining
> implementation files, unless those have been carefully written with
> pedagogy in mind.

You are wrong.  As a matter of fact, when I failed to understand the
discussion in TC++SL, I looked at the implementation files where I found
the clarification I was looking for.

>>  If the C++ Standard Committee cannot produce the Standard
>> Headers in the form of C++ source code as a means of declaring the API to
>> the Standard Library, how can they, or anybody, reasonably expect that
>> others should produce such interfaces for their libraries?
>
> The committee never had the intention of producing an implementation of
> C++. It exists to specify the language, not implement it. It will no more
> produce a library implementation than it would produce any other part of
> the compiler.

I did not write implementation.  I wrote "as a means of _declaring_ the API
to the Standard Library".
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Bob Bell wrote:

> "Steven T. Hatton" wrote:
>> thoth39 wrote:
>>
>> > This is the Internet. Put them up on a website somewhere.
>>
>> I'm sorry to hear that between sun Mircorsystems, IBM, Mircosoft, Oracle,
>> AT&T, and all the other companies who benefit from the C++ standard that
>> the cost of maintaining a representative collection of files declaring
>> the API to one of their most commonly used libraries should be the
>> inhibiting factor in producing such.
>
> Sun Microsystems, IBM, Microsoft, Oracle, AT&T and all the other
> companies you're thinking of haven't called this a problem, and haven't
> volunteered to fix it. Are they supposed to do it because _you_ say so?
> _I_ don't think you've identified a problem here, so should _I_ have to
> fix it?

Please review the context so that you can understnad the impication of my
statement.

> It's amazing that you've identified what you claim is a very serious
> problem, but you are willing to put more energy into explaining why
> someone else should fix it than into trying to fix it yourself.

That is not the case.  As a matter of fact, I volunteerd to provide the
files myself.

> Given
> this dichotomy between what you say ("it's a serious problem") and what
> you do (nothing), why should anyone else take the problem seriously?
> This is not a rhetorical question; I am honestly curious how you
> resolve this.
>
> I would think that, at the very least, you would want someone who is
> motivated to fix the problem. Someone who really believes there is a
> real problem, and who understands it so well that they can identify a
> real solution. This discounts me, for example; since I don't understand
> why what you describe is a problem, I'm not sure what a solution would
> look like. So far, only one person seems to fit this description, and I'm
> replying to his post.

I've already explaind my reaonsing.

> Funny, I think that objection applies to everyone else you've decided
> should fix this.

Then you should think a bit harder about what was intended.

> If you're used to working this way (i.e., consulting header files to
> understand an API), then you have my sympathies. Perhaps this is the
> problem you should be solving instead.

Actually, well written code is easier to understand than extensive prose
explaining it.

> You seem to equate "API" with "header files", which is the source of
> all of your problems in this area.

Please review the discussion, and consult the references I'ce cited.

> Ideally, such information should be available in a library's
> _documentation_, the clarity of which is not hampered by having to be a
> compilable, executable implementation of the API.

Every bit of this dicumentation is extracted from the source code, and the
comments therein.   Often the source code without any comments is
sufficient to communicate the essential aspects of the API.

http://java.sun.com/j2se/1.5.0/docs/api/index.html

For information on how to create C++ API documentation, please consult this
website:

http://www.stack.nl/~dimitri/doxygen/

> And which of these authors told you that the proper way to understand
> an API is to read the header(s) by which it is implemented?

Bjarne Stroustrup


--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:
> In particular it is inconsistent with what is written
> in TC++PL(SE) in the sections I've already cited.

Perhaps you missed page 434?
     "In general, implementers use standard headers in ways
      programmers cannot predict and shouldn't have to know
      about."

> There is a reasonable expectation that the Standad should be accessible as a
> reference to the language.

The only expectation is that the Standard correctly and completely
dexcribes the language it is specifying. The style of it is up to
the authors. It could be chatty like C and C++ or insanely formal
like Algol 68. In any case, it is meant as a precise description
for implementors, who are already assumed to be knowledgable in
the nuances of the language.

> Being able to view the entire API in the form
> of class (template) definitions and function declarations cannot be
> substituted by providing books about using it.

You really must find better books.

> This is a major reason for
> having such features as introspection which are core to both Java and C#.

Introspection is for programs to use, not people. It's so that
general purpose code can deal with objects whose types are not
compiled into the program. Certainly Java's introspection does
not involve creating a Java source code file!

> You can query a library and have it programmatically provide its public
> interface, or in some cases even more.  That feature is one of the biggest
> reason Java is easier to learn than C++.

This is certainly a unique point of view. I assure you that there is
no one in the world, except perhaps you, who learns how to program a
library by querying its interfaces programmatically. The most basic
reason is that doing so gives you no information about the semantics
of the interfaces you are discovering.

> Please review the previous conversation on this matter.
 > The meaning of my comments should then be clear to you.

It's clear enough to me that such an implementationless
implementation would be worse than useless, by needlessly
overconstraining library authors.

> That is your opinion.  In my opinion, you are describing
> a very bad way of providing an API.

But since this is how virtually all APIs are provided,
it would appear that my opinion is the one used, while
yours is not. Another way of saying this is that your
opinion is wrong.

> I did not write implementation.  I wrote "as a means of _declaring_ the API
> to the Standard Library".

That is part of the implementation. Declarations of types and
functions are a part of the implementation.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> See the discussion in
> _C++ Templates, The Complete Guide_, by van de Voorde and Josuttis, chapter
> 6 for a discussion of this.

OK, I just had a look at chapter 6. Perhaps you should be a little more
specific in your citation, because I don't see anything that supports
the idea that header files are a natural vehicle for describing an API,
while templates subvert this purpose.

If you have any citations supporting the idea that header files are a
good source of documentation, I'd be interested to know that.

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:
> Hyman Rosen wrote:
>
> > Steven T. Hatton wrote:
> >> the Standard Headers are the formal declaration of Standard Library API,
> >> and should be consulted in order to understand that API.
> >
> > APIs are documented, and the documentation should be consulted
> > to determine their proper use. Header files are part of the
> > implementation and contain things which are necessary for that.
> > There should be no expectation that the implementation serves
> > as the documentation.
>
> This is completely inconsistent with virtually everything I have ever read
> on program design.  In particular it is inconsistent with what is written
> in TC++PL(SE) in the sections I've already cited.

Perhaps you are referring to this citation:

> The textbook I used to learn C++ said that interfaces should be
> selfdescribing.  The Standard Headers are the interface between the
> programmer and the Standard Library implementation.  As such, they should
> be selfdescribing.
>
> http://www.research.att.com/~bs/3rd.html
> See:    8.2.4 and    24.4.2

In neither of these sections can I find a mention of interfaces as
"self-describing". Further, there doesn't seem to be anything that
supports your contention that such self-description must be present, in
a "readable to users" form, in header files. In fact, the use of the
term "interface" in those sections seems to be a logical concept, not a
physical one; I refer you to section 9.3 for examples of expressing the
_same_ interface in multiple different physical header file. These
examples suggest that, at least as used by Stroustrup, the terms
"interface" and "header file" are not synonymous.

Bob


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

""Steven T. Hatton"" <hattons@globalsymmetry.com> skrev i meddelandet
news:Sq6dnTpmpuCQpFnfRVn-pQ@speakeasy.net...
>
> Every bit of this dicumentation is extracted from the source code, and
> the
> comments therein.

A lousy way to document an interface, in my opinion. Why would you like
to compile all the documentation over and over again? What if you have a
technical writing staff separate from the programmers?

> Often the source code without any comments is
> sufficient to communicate the essential aspects of the API.
>
> http://java.sun.com/j2se/1.5.0/docs/api/index.html
>

That's just the documentation for one implementation of the Java
library. The fact that Sun will sue anyone that deviates, is all that
makes it an authority.

The C++ Standard does not dictate The One And Only Way to implement a
C++ library. There are several independent implementations, each with
its own documentation.

http://www.dinkumware.com/manuals/reader.aspx?lib=cpp
http://www.stlport.org/doc/index.html
http://www.sgi.com/tech/stl/
http://www.roguewave.com/support/docs/

What is the problem? That it is not all supplied by the Standards
Committee?


Bo Persson


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:
> Hyman Rosen wrote:
>
> > Steven T. Hatton wrote:
.
> ... Being able to view the entire API in the form
> of class (template) definitions and function declarations cannot be
> substituted by providing books about using it. ...

That's almost exactly backwards.  You can't substitute reading the
class (template) defintions and function declarations for actually
reading the documentation. Many of the standard library's class
template definitions and function declarations must, if they are
actually capable of working, contain implementation-specific features.
The standard describes what these features do, but in many cases it
deliberately avoids being too specific about how they do it. This
allows each implementation the freedom to choose the right way to
implement it for their systems. Given the nature of C++, those
implementation-specific details often affect not only the
implementation (which can be hidden if the 'export' keyword is
correctly implemented) but also the class (template) defintion, which
cannot be hidden. If you rely on looking at a standard library header,
rather than reading the standard itself, you might easily mistakenly
conclude that you can rely on one of those implementation-specific
features in code that was intended to be portable.

> > These so-called "Standard Headers" cannot be used because they do not
> > exist. The Standard does not specify their complete contents. Every
> > implementation supplies its own, correct for that implementation.
>
> Please review the previous conversation on this matter.  The meaning of my
> comments should then be clear to you.

That's a little too cryptic for me. Could you please explain further?
I'm not sure which comments you're referring to, nor which meaning
we're supposed to draw from them. Since I'm not sure which meaning it
is that you're referring to, I'm not sure what it has to do with Hyman
Rosen's comment above. Are you suggesting that his comment is false, or
irrelevant? Are you perhaps saying that you were already well aware of
the fact that it is both true and relevant, and that you didn't need to
be reminded of that fact?

> > Header files contain sufficient code so that the types and functions
> > they declare can be used by the compilation units which include them.
> > Source files contain the implementations which are not relevant to the
> > users of those types and functions. This is as true for templates as
> > for non-templates, given that we now have compilers with which implement
> > 'export'. There should be no expectation that any of these files serve
> > as documentation for the things they contain.
>
> That is your opinion.  In my opinion, you are describing a very bad way of
> providing an API.

You're entitled to that opinion. My personal experience is that even
well-written API declarations often have hidden implications that only
an expert could recognise. To take a simple case, a complete newbie to
C++ might not recognise on his own the implications of the fact that
the destructor for a given class is protected. If he copies correctly
written example code, it might be a long time before he does something
that produces an error message showing him why the destructor was
declared protected. Even then, if he hasn't read the documentation, he
might easily conclude that it was a mistake, and should have been
declared public.

You can and should supplement the code with internal documentation, but
in my experience the internal documentation is often just as
out-of-date and inaccurate as the external documentation, and is
usually harder to read.

There are several reasons why internal documentation is often harder to
read. First of all, it's intermixed with the code, interrupting the
flow of the language and the presentation. Secondly, there's more
freedom to format external documentation in a readable fashion, than
there is within the restrictions of C++ comments. Finally, it's
commonplace for the code, and therefore the in-code comments, to be
written by people whose command of English is not necessarily very
good, and who therefore often try to get away with writing as little as
possible. On sufficiently big projects, the external documentation is
written by experts in technical writing. Even on smaller projects,
documentation is reserved for the people with the best command of the
English language.

.
> You are wrong.  As a matter of fact, when I failed to understand the
> discussion in TC++SL, I looked at the implementation files where I found
> the clarification I was looking for.

You were merely lucky; in general getting the answers you need by
examining the implementation files require expertise comparable to that
of the person who wrote them, and the answer you get that way is often
more implementation-specific than you might expect.

.
> > The committee never had the intention of producing an implementation of
> > C++. It exists to specify the language, not implement it. It will no more
> > produce a library implementation than it would produce any other part of
> > the compiler.
>
> I did not write implementation.  I wrote "as a means of _declaring_ the API
> to the Standard Library".

Unfortunately, any header files that were actually useable with a
particular implementation would necessarily expose implementation
details that you should not be paying attention to.

Also, many of the important requirements for using an API cannot be
conveyed by the declaration, such as the fact that a given numerical
argument is required to be even (an example I ran into just this
afternoon). The documentation should describe those requirements. If
these additional requirements are simple enough, they might be
mentioned in the internal documentation, but the external documentation
is the right place to look for such information.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> Steven T. Hatton wrote:
>> Hyman Rosen wrote:
>>
>> > Steven T. Hatton wrote:
> .
>> ... Being able to view the entire API in the form
>> of class (template) definitions and function declarations cannot be
>> substituted by providing books about using it. ...
>
> That's almost exactly backwards.  You can't substitute reading the
> class (template) defintions and function declarations for actually
> reading the documentation.

Reading implementation-provided documentation may likewise be misleading if
it happens to give a wrong impression as to what the Standard actually
states.  When in doubt, I typically consult the Standard.

> Many of the standard library's class
> template definitions and function declarations must, if they are
> actually capable of working, contain implementation-specific features.

If you are talking about things such as iterators in container classes, I
have to ask what difference that makes to the subject at hand.

> The standard describes what these features do, but in many cases it
> deliberately avoids being too specific about how they do it. This
> allows each implementation the freedom to choose the right way to
> implement it for their systems. Given the nature of C++, those
> implementation-specific details often affect not only the
> implementation (which can be hidden if the 'export' keyword is
> correctly implemented) but also the class (template) defintion, which
> cannot be hidden.

I'm not convinced.  I am aware of very specific places where the
implementation is required to provide definitions.  There may be a few
quirks in the Standard that force the implementation to include some minor
adjustments, but I believe that most of the Standard Headers could be
implemented by providing the interface specified in the Standard in
associated header files that map one-to-one, or very closely to the
Standard Headers.

> If you rely on looking at a standard library header,
> rather than reading the standard itself, you might easily mistakenly
> conclude that you can rely on one of those implementation-specific
> features in code that was intended to be portable.

Well, at least you aren't telling me I can't use the standard effectively as
a reference. (My original post suggested improving its usability for that
purpose.)  I never advocated using the proposed representative source files
as the exclusive resource for gaining information about the Standard
Library.

>> > These so-called "Standard Headers" cannot be used because they do not
>> > exist. The Standard does not specify their complete contents. Every
>> > implementation supplies its own, correct for that implementation.
>>
>> Please review the previous conversation on this matter.  The meaning of
>> my comments should then be clear to you.
>
> That's a little too cryptic for me. Could you please explain further?

Copy the entire Standard Library specification to a text file.  Delete all
the text that does not represent actual source code declaring entities
within the Standard Headers.  Add comments indicating the page number,
clause and section where the text appears in the Standard.  Break the
resulting file into separate files with names representative of the
specific headers where these declarations are specified to appear.

> I'm not sure which comments you're referring to, nor which meaning
> we're supposed to draw from them. Since I'm not sure which meaning it
> is that you're referring to, I'm not sure what it has to do with Hyman
> Rosen's comment above. Are you suggesting that his comment is false, or
> irrelevant?

Basically irrelevant.  It's like telling me there is no std::list in C++
because std::list is a concept not an instantiated object.

> Are you perhaps saying that you were already well aware of
> the fact that it is both true and relevant, and that you didn't need to
> be reminded of that fact?

Not at all.  See page 21 of TC++PL(SE) for an explanation of the point I was
making.

>> > Header files contain sufficient code so that the types and functions
>> > they declare can be used by the compilation units which include them.
>> > Source files contain the implementations which are not relevant to the
>> > users of those types and functions. This is as true for templates as
>> > for non-templates, given that we now have compilers with which
>> > implement 'export'. There should be no expectation that any of these
>> > files serve as documentation for the things they contain.
>>
>> That is your opinion.  In my opinion, you are describing a very bad way
>> of providing an API.
>
> You're entitled to that opinion. My personal experience is that even
> well-written API declarations often have hidden implications that only
> an expert could recognise. To take a simple case, a complete newbie to
> C++ might not recognise on his own the implications of the fact that
> the destructor for a given class is protected. If he copies correctly
> written example code, it might be a long time before he does something
> that produces an error message showing him why the destructor was
> declared protected.

All that takes is a newbie to the concept of inherited reference counting.

> Even then, if he hasn't read the documentation, he
> might easily conclude that it was a mistake, and should have been
> declared public.

I never said documentation has no role to play in communicating programmer
intent.

> You can and should supplement the code with internal documentation, but
> in my experience the internal documentation is often just as
> out-of-date and inaccurate as the external documentation, and is
> usually harder to read.

Stroustrup makes some comments about this in TC++PL(SE).  Your comment seems
somewhat orthogonal to the discussion at hand.  I will say this, since you
brought it up, modern documentation systems such as Doxygen provide a
wonderful means of combining internal documentation with the formal API
specification (external documentation.)  I'm not sure who has precedence in
this, but both Doxygen and JavaDoc are very powerful tools.

> There are several reasons why internal documentation is often harder to
> read. First of all, it's intermixed with the code, interrupting the
> flow of the language and the presentation. Secondly, there's more
> freedom to format external documentation in a readable fashion, than
> there is within the restrictions of C++ comments. Finally, it's
> commonplace for the code, and therefore the in-code comments, to be
> written by people whose command of English is not necessarily very
> good, and who therefore often try to get away with writing as little as
> possible. On sufficiently big projects, the external documentation is
> written by experts in technical writing. Even on smaller projects,
> documentation is reserved for the people with the best command of the
> English language.

Quite often there is little, or no need to add comments to a particular
declaration, and commenting the declaration actually detracts from the
readability of the code, and bloats the API specification.

Back to your original point about needing more than the bare declaration of
the interface in order to understand how to use it.  A better, and more
apropos example might be be the declarations in <algorithm>.  These simply
do not communicate all that is needed in order to use the associated
functions.  You really need access to either the implementation, or
documentation describing what the functions do.

The only reliable way to know that you have a correct understanding of what
the Standard specifies regarding a particular item is to read the Standard
with understanding.

>> You are wrong.  As a matter of fact, when I failed to understand the
>> discussion in TC++SL, I looked at the implementation files where I found
>> the clarification I was looking for.
>
> You were merely lucky; in general getting the answers you need by
> examining the implementation files require expertise comparable to that
> of the person who wrote them, and the answer you get that way is often
> more implementation-specific than you might expect.

I don't know if that really applies to most of the Standard Library.  Much
of it's kind of ho-hum; binary function object for addition, binary
function object for subtraction, etc.  The case in point was Chapter 8, and
the discussion of mem_fun verses mem_fun_t.  Until I actually looked at the
implementation, it was not clear to me that the former represents a
function while the latter represents a function object.

> .
>> > The committee never had the intention of producing an implementation of
>> > C++. It exists to specify the language, not implement it. It will no
>> > more produce a library implementation than it would produce any other
>> > part of the compiler.
>>
>> I did not write implementation.  I wrote "as a means of _declaring_ the
>> API to the Standard Library".
>
> Unfortunately, any header files that were actually useable with a
> particular implementation would necessarily expose implementation
> details that you should not be paying attention to.

Though I am not convinced of the correctness of your assertion, I don't see
it as relevant to the discussion.  I am talking about a representative
collection of non-normative source files provided for exposition.

> Also, many of the important requirements for using an API cannot be
> conveyed by the declaration, such as the fact that a given numerical
> argument is required to be even (an example I ran into just this
> afternoon). The documentation should describe those requirements. If
> these additional requirements are simple enough, they might be
> mentioned in the internal documentation, but the external documentation
> is the right place to look for such information.

But sometimes I just want to see a listing of all the available signatures
for all the available find_... functions in basic_string<>. I'll know what
they do when I see them if I've already read the documentation.  And if I
don't know what they do, I know what to look for in the documentation.

Before I undertook the exercise of actually collecting these declarations
into representative files, I had a nebulous grasp of what it really meant
to include, for example, <string> in my program.  Now that I can view all
the template definitions, and function declarations in one file without
additional clutter, I have a solid sense of what it means.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Bo Persson wrote:

>
> ""Steven T. Hatton"" <hattons@globalsymmetry.com> skrev i meddelandet
> news:Sq6dnTpmpuCQpFnfRVn-pQ@speakeasy.net...
>>
>> Every bit of this dicumentation is extracted from the source code, and
>> the
>> comments therein.
>
> A lousy way to document an interface, in my opinion. Why would you like
> to compile all the documentation over and over again?

Why would I need to?  The only time I need to recompile the documentation (a
process that often takes far less time than compiling the C++ source) is
when I change the interface.  And guess what.  Quite often, I don't have to
change the human generated parts of the documentation.  I can run a program
that generates the documentation with all the corrections to reflect the
current code.

> What if you have a
> technical writing staff separate from the programmers?

Do your really want a person with a degree in English documenting your API?

>> Often the source code without any comments is
>> sufficient to communicate the essential aspects of the API.
>>
>> http://java.sun.com/j2se/1.5.0/docs/api/index.html
>>
>
> That's just the documentation for one implementation of the Java
> library.

That's really irrelevant to the example presented.  If I write my own Java
code, the tools that are provided with the Java distribution will generate
documentation of exactly the same form as the Java API documentation.

For example:
http://xml.apache.org/xerces2-j/javadocs/xerces2/

> The fact that Sun will sue anyone that deviates, is all that makes it an
> authority.

What makes it authoritative for the particular implementation is that it was
extracted directly from the source code, and therefore exactly reflects the
public interface.  But please bear in mind that I have not suggested the
C++ Headers be made available by the Standard Committee with full Doxygen
commenting and markup.  (Not that I believe it's a bad idea, I just believe
it's a lost cause.)

> The C++ Standard does not dictate The One And Only Way to implement a
> C++ library. There are several independent implementations, each with
> its own documentation.

I never said the Standard does dictate one and only one way to implement the
Standard Library.  I never said the Standard /should/ dictate that.  The
most I suggested should be included with the Standard is a "representative"
collection of files - non-normative, for purposes of exposition.

> http://www.dinkumware.com/manuals/reader.aspx?lib=cpp
> http://www.stlport.org/doc/index.html
> http://www.sgi.com/tech/stl/
> http://www.roguewave.com/support/docs/

When I need API documentation, I consult the Standard, or the source files I
have extracted from it.  For example, earlier today a person on c.l.c++
asked whether `"NTBS" + std::string("Some string");' returning std::string,
was proper C++.  I simply looked at the clause in the standard:

ISO/IEC 14882:2003(E)     21.3.7.1
    template<class charT, class traits, class Allocator>
      basic_string<charT,traits,Allocator>
         operator+(const charT* lhs,
                   const basic_string<charT,traits,Allocator>& rhs);
Returns: basic_string<charT,traits,Allocator>(lhs) + rhs.

> What is the problem? That it is not all supplied by the Standards
> Committee?

No.  The problem is that I cannot look at the source files representing the
API.  HTML API documentation is nice, but it is really not a substitute for
seeing the source code form of the declarations. One very nice feature of
Doxygen is that it will strip the comments from the source files, and
present them with HTML links into the API documentation.  Even that will
not serve the same purposes as having the actual declarations in raw source
form.

Now let me draw some distinctions.

I was not going to continue discussing this issue until it was insinuated
that I merely wanted someone else to do my work for me.

Though I believe it would add considerable value to have the C++ Standard
Library specified in the form of representative header files with Doxygen,
or similar markup used to generate the prose, I have not suggested such a
thing actually be done.

What I *did* suggest is that the Standard Committee make available a
collection of source files /representative/ of the Standard Headers.

And if I have not made this explicit, let me do so now:  I suggest that one
of the most important audiences for these representative source files
should be the members of the Standard Committee themselves.

I have stated that having these files available in source form would make it
easier to learn the C++ Standard Library API, and that it would make it
easier to use the API.  That is not speculation.  That is the voice of
experience.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" <hattons@globalsymmetry.com> wrote in message
news:QcqdneeVUoPNDFnfRVn-uw@speakeasy.net...

> Now let me draw some distinctions.
>
> I was not going to continue discussing this issue until it was insinuated
> that I merely wanted someone else to do my work for me.

In your original posting, you said:

: It seems reasonable to me that the Standard Committee would make the
: standard header declarations available in the form that they are presented
: in the Standard, but as separate files holding nothing but the header
: declarations, and references back to the relevant text in the Standard.

Then Pete Becker said:

: Volunteering other people to do this work won't get it done. Write it up
: and propose it.

And you replied:

: As far as who actually does the work, I would expect the people working on
a
: particular part of the Standard would be most qualified to provide the
file
: for their particular header.  To a person familiar with given section of
: the Standard associated with a Header, this should constitute about 10
: minutes of work.

> Though I believe it would add considerable value to have the C++ Standard
> Library specified in the form of representative header files with Doxygen,
> or similar markup used to generate the prose, I have not suggested such a
> thing actually be done.

In the same posting, you said:

: The idea crossed my mind that it might also be useful to put much of the
: text of the standard in C++ comment blocks, perhaps with Doxygen markup.
: This, of course, would require more work, and more politics.

P.J. Plauger
Dinkumware, Ltd.
http://www.dinkumware.com


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Bob Bell wrote:
>
> > "Steven T. Hatton" wrote:
> >> thoth39 wrote:
> >>
> >> > This is the Internet. Put them up on a website somewhere.
> >>
> >> I'm sorry to hear that between sun Mircorsystems, IBM, Mircosoft, Oracle,
> >> AT&T, and all the other companies who benefit from the C++ standard that
> >> the cost of maintaining a representative collection of files declaring
> >> the API to one of their most commonly used libraries should be the
> >> inhibiting factor in producing such.
> >
> > Sun Microsystems, IBM, Microsoft, Oracle, AT&T and all the other
> > companies you're thinking of haven't called this a problem, and haven't
> > volunteered to fix it. Are they supposed to do it because _you_ say so?
> > _I_ don't think you've identified a problem here, so should _I_ have to
> > fix it?
>
> Please review the context so that you can understnad the impication of my
> statement.

I have; I've followed this thread from the beginning. If there is an
implication in your statements that is not clear from your text,
perhaps you should spell it out; I can't read your mind.

> > It's amazing that you've identified what you claim is a very serious
> > problem, but you are willing to put more energy into explaining why
> > someone else should fix it than into trying to fix it yourself.
>
> That is not the case.  As a matter of fact, I volunteerd to provide the
> files myself.

And when you asked where to put them, thoth39 suggested that you, "Put
them up on a website somewhere." Your response was an additional
two-page description of the problem which began with a suggestion that
Sun, et. al. maintain a set of files. As it is pretty clear that
solving the problem you're after includes maintaining these files -- or
did you think they would conform themselves as the language evolves? --
it sounded to me like you were explaining that someone else should fix
the problem.

> > Given
> > this dichotomy between what you say ("it's a serious problem") and what
> > you do (nothing), why should anyone else take the problem seriously?
> > This is not a rhetorical question; I am honestly curious how you
> > resolve this.
> >
> > I would think that, at the very least, you would want someone who is
> > motivated to fix the problem. Someone who really believes there is a
> > real problem, and who understands it so well that they can identify a
> > real solution. This discounts me, for example; since I don't understand
> > why what you describe is a problem, I'm not sure what a solution would
> > look like. So far, only one person seems to fit this description, and I'm
> > replying to his post.
>
> I've already explaind my reaonsing.

And I've refuted it. Where does that leave us?

> > Funny, I think that objection applies to everyone else you've decided
> > should fix this.
>
> Then you should think a bit harder about what was intended.

Your objection about copyrighted materials is easily addressed:

Steven: C++ Committee, can I use these copyrighted materials in a
proposal for C++?
C++ Committee: Go ahead.

I don't know if it would actually be that simple, but -- if you really
think the copyright issue is an obstacle -- did you even try to get
around it?

> > If you're used to working this way (i.e., consulting header files to
> > understand an API), then you have my sympathies. Perhaps this is the
> > problem you should be solving instead.
>
> Actually, well written code is easier to understand than extensive prose
> explaining it.

Uh huh. You can look at well-written code (by which you must mean code
in header files, because that's what we've been discussing) and tell
what the author meant? What the limit cases are for each function? What
dependencies they have in terms of calling order, or any changes they
might make to shared state? The meaning of each class, and how they
collaborate? What the exceptional cases are, and how each function
responds to them? What the valid return values are, and how to
interpret them? Etc., etc., etc.

You've got one on me; I sure can't do that.

> > You seem to equate "API" with "header files", which is the source of
> > all of your problems in this area.
>
> Please review the discussion, and consult the references I'ce cited.

I have; as far as I can see they don't support your conclusion. Perhaps
more focused citations (page numbers, quotes, etc.) would help.

> > Ideally, such information should be available in a library's
> > _documentation_, the clarity of which is not hampered by having to be a
> > compilable, executable implementation of the API.
>
> Every bit of this dicumentation is extracted from the source code, and the
> comments therein.

This is a pretty broad claim, easily disproven with counter-examples.
For one, I myself have written API documentation for several libraries
over the years without extracting anything from the source code other
than my own understanding of the semantics.

That's the problem with this idea of header-files-as-documentation. A
header file contains definitions and declarations, which are all
syntactic in nature; they really carry no semantics at all. Since
understanding how to use a library is more about semantics than syntax,
relying on header files will always involve the reader trying to infer
semantics from syntax. Sounds pretty unreliable to me.

> Often the source code without any comments is
> sufficient to communicate the essential aspects of the API.
>
> http://java.sun.com/j2se/1.5.0/docs/api/index.html
>
> For information on how to create C++ API documentation, please consult this
> website:
>
> http://www.stack.nl/~dimitri/doxygen/

Oddly enough, neither of these examples support the idea that
programmers should look at header files in order to understand how to
use a library.

I don't work in Java, so I can't really say much about it; however, I
do use C++ with doxygen. Have you ever looked at a header file that was
seriously doxygenated? The generated documentation may be easy to read
and follow, but the header file is a mess. Why, if you've got
doxygenated files, would you look at the headers instead of the
generated documentation?

> > And which of these authors told you that the proper way to understand
> > an API is to read the header(s) by which it is implemented?
>
> Bjarne Stroustrup

Hyman has already posted a citation which pretty thoroughly debunks
this claim.

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

>> And which of these authors told you that the proper way to understand
>> an API is to read the header(s) by which it is implemented?
>
> Bjarne Stroustrup

Did he? Where? Please quote a paragraph and page number. Thank you.

BTW, when you do

#include <iostream>

there is no reason that why "#include <iostream>" means that there has to be
a file called iostream.
Vendors don't have implement this in terms of files.
 So you would have nothing to study in this case.

Stephen Howe


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" <hattons@globalsymmetry.com> skrev i meddelandet
news:QcqdneeVUoPNDFnfRVn-uw@speakeasy.net...
> Bo Persson wrote:
>
>>
>> ""Steven T. Hatton"" <hattons@globalsymmetry.com> skrev i meddelandet
>> news:Sq6dnTpmpuCQpFnfRVn-pQ@speakeasy.net...
>>>
>>> Every bit of this dicumentation is extracted from the source code,
>>> and
>>> the
>>> comments therein.
>>
>> A lousy way to document an interface, in my opinion. Why would you
>> like
>> to compile all the documentation over and over again?
>
> Why would I need to?  The only time I need to recompile the
> documentation (a
> process that often takes far less time than compiling the C++ source)
> is
> when I change the interface.  And guess what.  Quite often, I don't
> have to
> change the human generated parts of the documentation.  I can run a
> program
> that generates the documentation with all the corrections to reflect
> the
> current code.
>

I was more thinking about that adding all the documentation to the
header files would make then much larger. That would not improve the
compile time for the code.


>> What if you have a
>> technical writing staff separate from the programmers?
>
> Do your really want a person with a degree in English documenting your
> API?

No, but someone with some writing skills. Perhaps someone native in
English. I'm not.

Also, good programmers can expensive. Why waste that on something they
don't do well?

>
>>> Often the source code without any comments is
>>> sufficient to communicate the essential aspects of the API.

So you mean the C++ Committee wasted 300 pages on describing the library
API, when they should have concentrated on producing a set of reference
headers? (possibly without comments :-).


>>>
>>> http://java.sun.com/j2se/1.5.0/docs/api/index.html
>>>
>>
>> That's just the documentation for one implementation of the Java
>> library.
>
> That's really irrelevant to the example presented.  If I write my own
> Java
> code, the tools that are provided with the Java distribution will
> generate
> documentation of exactly the same form as the Java API documentation.

It's totally relevant, because of the different status of C++ and Java.
Sun is the "committee" for Java, and can publish a reference
implementation because there can only be one.

When MS tried to supply a modifed Java library, they were sued, and got
a court order forbidding them to do that. That's why we know that Sun's
implementation is The One and Only true Java.


[...]

> When I need API documentation, I consult the Standard, or the source
> files I
> have extracted from it.  For example, earlier today a person on
> c.l.c++
> asked whether `"NTBS" + std::string("Some string");' returning
> std::string,
> was proper C++.  I simply looked at the clause in the standard:
>
> ISO/IEC 14882:2003(E)     21.3.7.1
>    template<class charT, class traits, class Allocator>
>      basic_string<charT,traits,Allocator>
>         operator+(const charT* lhs,
>                   const basic_string<charT,traits,Allocator>& rhs);
> Returns: basic_string<charT,traits,Allocator>(lhs) + rhs.

That might depend on your IDE. I don't use KDevelop, but Visual Studio
on Windows. There I press F1 for help when I need to consult the
documentation. I very much prefer the 1 GB of technical writing over the
header files.

I very rarely have to look in the headers. It might be when I get a
particularly nasty compile error for some  templates. Sometimes the
error message points to some line in a header. I might then look there
to try to figure out what's wrong (ususally in my code, of course).

[...]


> What I *did* suggest is that the Standard Committee make available a
> collection of source files /representative/ of the Standard Headers.
>

I belive that they are a bit reluctant to do that, not just because of
extra work involved. From earlier discussions it seems that they don't
want to publish more than one version of the standard, because of the
risk for additional confusion. If the reference headers were found not
to fully follow the requirements of the Standard text, then what?


Bo Persson


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Bo Persson wrote:
>
> When MS tried to supply a modifed Java library, they were sued, and got
> a court order forbidding them to do that. That's why we know that Sun's
> implementation is The One and Only true Java.
>

Java and the Microsoft suit are off-topic for this newsgroup, but I cannot let
this false statement stand.

The Java license concerns the Java trademark. The license requires that an
implemention pass the Java validation suite. Extensions are explicitly allowed
by the license, but must be clearly marked as extensions. Having met these
requirements, an implementation *is* Java, and can use the Java trademark.

Sun claimed in its suit that Microsoft violated both of the requirements I
mentioned above, constituting violations of the Java license and infringement
of the trademark. The suit was settled last year. Microsoft paid an indemnity
to Sun, and the two companies are now cooperating on making the technologies of
each company interoperable.

Further discussion of this topic should be taken to another newsgroup.

---
Steve Clamage, stephen.clamage@sun.com

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Stephen Howe wrote:

>>> And which of these authors told you that the proper way to understand
>>> an API is to read the header(s) by which it is implemented?
>>
>> Bjarne Stroustrup
>
> Did he? Where? Please quote a paragraph and page number. Thank you.

Read the book.

> BTW, when you do
>
> #include <iostream>
>
> there is no reason that why "#include <iostream>" means that there has to
> be a file called iostream.
> Vendors don't have implement this in terms of files.

I have already, repeatedly stated that I understand there is no requirement
that the Standard Headers be implemented as actual files.

>  So you would have nothing to study in this case.

And so what _is_ required of the implementation in order to provide the
correct behavior when #include <iostream> is added to C++ code?  If it is
not a collection of templated class definitions, function declaration, and
a few global or namespace local constants, please let me know.  Of course,
I acknowledge there are a limited number of clearly defined places where
the implementation is required to provide its own definitions.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Bo Persson wrote:

>=20
> "Steven T. Hatton" <hattons@globalsymmetry.com> skrev i meddelandet
> news:QcqdneeVUoPNDFnfRVn-uw@speakeasy.net...
>> Bo Persson wrote:
>>
>>>
>>> ""Steven T. Hatton"" <hattons@globalsymmetry.com> skrev i meddelandet
>>> news:Sq6dnTpmpuCQpFnfRVn-pQ@speakeasy.net...
>>>>
>>>> Every bit of this dicumentation is extracted from the source code,
>>>> and
>>>> the
>>>> comments therein.
>>>
>>> A lousy way to document an interface, in my opinion. Why would you
>>> like
>>> to compile all the documentation over and over again?
>>
>> Why would I need to?  The only time I need to recompile the
>> documentation (a
>> process that often takes far less time than compiling the C++ source)
>> is
>> when I change the interface.  And guess what.  Quite often, I don't
>> have to
>> change the human generated parts of the documentation.  I can run a
>> program
>> that generates the documentation with all the corrections to reflect
>> the
>> current code.
>>
>=20
> I was more thinking about that adding all the documentation to the
> header files would make then much larger. That would not improve the
> compile time for the code.

I don't believe stripping comments from source files is very much work fo=
r
the CPP.  If you want a good demonstration of wasted processing effort, I
suggest downloading gccxml and running it against a simple C++ program wi=
th
#include <sstream> in it.  Examining the resulting XML output will reveal
just how truly crude and inefficient the current concept of a translation
unit really is.

>=20
>>> What if you have a
>>> technical writing staff separate from the programmers?
>>
>> Do your really want a person with a degree in English documenting your
>> API?
>=20
> No, but someone with some writing skills. Perhaps someone native in
> English. I'm not.
>=20
> Also, good programmers can expensive. Why waste that on something they
> don't do well?

Regardless, when it comes to API documentation, my experience is that
generating it from sourcecode with, or without human generated comments
contained in specially marked comment blocks, is superior to trying to
maintain completely separate files.  If the actual declarations change in
the source code, the accompanying comments may get out of synch.  If the
programmer understands what parts are actually generated from the source
code there's a good chance the correct API will be appearant even in the
face of incorrect comments.

>>
>>>> Often the source code without any comments is
>>>> sufficient to communicate the essential aspects of the API.
>=20
> So you mean the C++ Committee wasted 300 pages on describing the librar=
y
> API, when they should have concentrated on producing a set of reference
> headers? (possibly without comments :-).

No. One approach to providing the Standard Library specification could,
however, be to place the text describing the API in comment blocks. The
actual C++ definitions and declarations required for each header would be
expressed in the form of C++ source code.  IOW, treat the C++ Standard
Library as if it were a real API specification.

>>>>
>>>> http://java.sun.com/j2se/1.5.0/docs/api/index.html
>>>>
>>>
>>> That's just the documentation for one implementation of the Java
>>> library.
>>
>> That's really irrelevant to the example presented.  If I write my own
>> Java
>> code, the tools that are provided with the Java distribution will
>> generate
>> documentation of exactly the same form as the Java API documentation.
>=20
> It's totally relevant, because of the different status of C++ and Java.
> Sun is the "committee" for Java, and can publish a reference
> implementation because there can only be one.

What about the (internal) Xerces API I presented?

Take a look at the W3C Document Object Model (DOM) Level 2 Core
Specification:

http://www.w3.org/TR/DOM-Level-2-Core/

In particular the Java language binding:

http://www.w3.org/TR/DOM-Level-2-Core/java-binding.html

I encourage you to download and examine the actual Java source code:

http://www.w3.org/TR/DOM-Level-2-Core/java-binding.zip

That source code represents the API for the DOM.  It consists of nothing =
but
interfaces (comperable to C++ abstract base classes).  These source files
in which the interfaces are defined also contain the complete API
specification.  A user of the API can write code directly to that API and
be sure that any conforming implementation will support that code
correctly.

I would provide the comperable C++ language binding, but it seems the C++
community was unable to produce (or agree upon) one.

There /is/, however, the Apache recommendation:

http://xml.apache.org/xerces-c/ApacheDOMC++BindingL2.html

> When MS tried to supply a modifed Java library, they were sued, and got
> a court order forbidding them to do that. That's why we know that Sun's
> implementation is The One and Only true Java.

There's really no difference in terms of conforming to the respective
specified APIs.  In the case of C++ you don't get sued, you get
excommunicated.  But this is not a question of how the API is implemented=
.=20
It is a question of _if_ this API is implemented (correctly).=20

> [...]
>=20
>> When I need API documentation, I consult the Standard, or the source
>> files I
>> have extracted from it.  For example, earlier today a person on
>> c.l.c++
>> asked whether `"NTBS" + std::string("Some string");' returning
>> std::string,
>> was proper C++.  I simply looked at the clause in the standard:
>>
>> ISO/IEC 14882:2003(E) =A7 21.3.7.1
>>    template<class charT, class traits, class Allocator>
>>      basic_string<charT,traits,Allocator>
>>         operator+(const charT* lhs,
>>                   const basic_string<charT,traits,Allocator>& rhs);
>> Returns: basic_string<charT,traits,Allocator>(lhs) + rhs.
>=20
> That might depend on your IDE. I don't use KDevelop, but Visual Studio
> on Windows. There I press F1 for help when I need to consult the
> documentation.

The person asking the question was using VC++, not me.

> I very much prefer the 1 GB of technical writing over the=20
> header files.

I don't use KDevelop very much these days either. I use Emacs.  But I
believe you have just identified the main motivation for objecting to my
suggestion.  My suggestion would even the playing field and reduce
artificial barriers to entry.

> I very rarely have to look in the headers. It might be when I get a
> particularly nasty compile error for some  templates. Sometimes the
> error message points to some line in a header. I might then look there
> to try to figure out what's wrong (ususally in my code, of course).

I don't _have_ to look at the Headers, I _want_ to look at the headers.  =
To
me, seeing the formal declaration of the API in source form is the best w=
ay
know what the the formal declaration of the API in source form looks like.

>> What I *did* suggest is that the Standard Committee make available a
>> collection of source files /representative/ of the Standard Headers.
>>
>=20
> I belive that they are a bit reluctant to do that, not just because of
> extra work involved. From earlier discussions it seems that they don't
> want to publish more than one version of the standard, because of the
> risk for additional confusion. If the reference headers were found not
> to fully follow the requirements of the Standard text, then what?

The Standard Committee would have demonstrated that even they are incapab=
le
of expressing the formal declaration of the API in source form.  But to m=
e
the objection is absurd.  All that implementing the suggestion would
require is marking certain parts of the Standard document to indicate tha=
t
it should also be included in the appendix containing the formal
declaration of the API in source form.
--=20
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Stephen Howe wrote:
>
> >>> And which of these authors told you that the proper way to understand
> >>> an API is to read the header(s) by which it is implemented?
> >>
> >> Bjarne Stroustrup
> >
> > Did he? Where? Please quote a paragraph and page number. Thank you.
>
> Read the book.

I have. Didn't see it. If it was there, and I missed it, and you claim
to have seen it, it helps your case enormously if you can tell me
where.

When you make a claim about a book that is in conflict with my memory
of that book, I'm entitled to assume that your refusal to provide a
more specific citation is because you can't provide one.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Stephen Howe wrote:
>
> >>> And which of these authors told you that the proper way to understand
> >>> an API is to read the header(s) by which it is implemented?
> >>
> >> Bjarne Stroustrup
> >
> > Did he? Where? Please quote a paragraph and page number. Thank you.
>
> Read the book.

I have read "the book", which I take to mean C++PL 3rd ed, and never
read any statement to the effect that the proper way to understand an
API is to read the header(s) by which it is implemented. One of us has
obviously misunderstood something in the book. If it's me, I'd like to
know, so that I can correct my misunderstanding. I would like to give
you the benefit of the doubt and assume that you are similarly
open-minded, and eager to correct any potential misunderstanding you
might have. Only you know what section of the book is pertinent to this
issue, and only by making that section public can the issue be
resolved. Therefore, we both have an interest in you posting a citation
that says what you think it says.

On the other hand, making vague references like "read the book", which
only makes it more difficult to evaluate your claims, lends weight to
the idea that you may not actually be open to the possibility that
you've misinterpreted the book, since vague references make it more
difficult to track down the misinterpretation.

But as I said, I'd like to give you the benefit of the doubt. Please
post a detailed citation where Bjarne Stroustrup stated that the proper
way to understand an API is to read the header(s) by which it is
implemented.

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
>
> > Steven T. Hatton wrote:
> >> Hyman Rosen wrote:
> >>
> >> > Steven T. Hatton wrote:
> > .
> >> ... Being able to view the entire API in the form
> >> of class (template) definitions and function declarations cannot be
> >> substituted by providing books about using it. ...
> >
> > That's almost exactly backwards.  You can't substitute reading the
> > class (template) defintions and function declarations for actually
> > reading the documentation.
>
> Reading implementation-provided documentation may likewise be misleading if
> it happens to give a wrong impression as to what the Standard actually
> states.  When in doubt, I typically consult the Standard.

In this context, the documentation I was referring to was the Standard.
However, looking at the implementation-provided documentation isn't a
bad idea, either; both are better ideas than looking at any specific
implementation that happens to meet the Standard's requirements.

> > Many of the standard library's class
> > template definitions and function declarations must, if they are
> > actually capable of working, contain implementation-specific features.
>
> If you are talking about things such as iterators in container classes, I
> have to ask what difference that makes to the subject at hand.

You're talking about creating something that looks like it would be
constitute a suitable set of header files to #include in preparation
for linking to the C++ standard library, but which in general could NOT
be used that way with any particular implementation of that library. I
understand from your comments below that you don't actually intend for
it to actually be a complete set of headers; that was a
misunderstanding on my part. However, an incomplete set has it's own
dangers, principly due to the fact that users are likely to assume that
it is complete.

.
> > That's a little too cryptic for me. Could you please explain further?
>
> Copy the entire Standard Library specification to a text file.  Delete all
> the text that does not represent actual source code declaring entities
> within the Standard Headers.  Add comments indicating the page number,
> clause and section where the text appears in the Standard.  Break the
> resulting file into separate files with names representative of the
> specific headers where these declarations are specified to appear.

OK. That's a less ambitious suggestion than the one I thought you were
making. I'd assumed you wanted something that could actually be the
implementation of the standard headers. The fact that it's less
ambitious means that it's easier to do, but also more pointless.

> Not at all.  See page 21 of TC++PL(SE) for an explanation of the point I was
> making.

I have the Third Edition, not the second. In my copy, page 21 is
section 2.1, titled "What is C++?", and it says nothing that I
recognise as relevant to this discussion. Suggestion: even different
copies of the same edition can have different page numberings; I'd
recommend using section numbers combined with titles, to maximize the
likelihood that someone will be able to follow up on your citations. Of
course, for best effects it helps if you explain what feature it is of
the text you're citing that is relevant to the context you're citing it
in.

> > Even then, if he hasn't read the documentation, he
> > might easily conclude that it was a mistake, and should have been
> > declared public.
>
> I never said documentation has no role to play in communicating programmer
> intent.

No, but you did suggest, mistakenly in my opinion, that it would be
helpful to collect all of the examples of standard header source code
from the standard into one location. I don't see any advantage from
that, unless the result would be a complete declaration for the
corresponding section of the standard library. However, in order to
gain that advantage, it must also possess the disadvantages I've been
describing.

.
> function object for subtraction, etc.  The case in point was Chapter 8, and
> the discussion of mem_fun verses mem_fun_t.  Until I actually looked at the
> implementation, it was not clear to me that the former represents a
> function while the latter represents a function object.

This is not meant as a criticism, I just want to understand the
context: what had your thoughts about mem_fun_t and mem_fun been,
before you looked at the implementation?

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

> Clearly, he thinks in terms of actual header files, as do many C++
> programmers.  If the C++ Standard Committee cannot produce the Standard
> Headers in the form of C++ source code as a means of declaring the API to
> the Standard Library, how can they, or anybody, reasonably expect that
> others should produce such interfaces for their libraries?

Suppose it was as you said and that C++ standard did contain model header
files.
Would you expect C++ vendors to produce header files identical to the
standard even if it meant it was sub-optimal for the platform the vendors
were targeting?

Stephen Howe


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> kuyper@wizard.net wrote:

>> Reading implementation-provided documentation may likewise be misleading
>> if it happens to give a wrong impression as to what the Standard actually
>> states.  When in doubt, I typically consult the Standard.
>
> In this context, the documentation I was referring to was the Standard.
> However, looking at the implementation-provided documentation isn't a
> bad idea, either; both are better ideas than looking at any specific
> implementation that happens to meet the Standard's requirements.

The implementation provided documentation and the implementation are
one-in-the-same for the implementation I use.  Unfortunately, neither
provide the view I am describing in my suggestion.

> You're talking about creating something that looks like it would be
> constitute a suitable set of header files to #include in preparation
> for linking to the C++ standard library, but which in general could NOT
> be used that way with any particular implementation of that library. I
> understand from your comments below that you don't actually intend for
> it to actually be a complete set of headers; that was a
> misunderstanding on my part. However, an incomplete set has it's own
> dangers, principly due to the fact that users are likely to assume that
> it is complete.

As an interface, it should be complete. The implementation defined
components can be easily and clearly marked.  I've already stated that the
appendix would contain references back to the relevant text of the
Standard.

> OK. That's a less ambitious suggestion than the one I thought you were
> making. I'd assumed you wanted something that could actually be the
> implementation of the standard headers. The fact that it's less
> ambitious means that it's easier to do, but also more pointless.

I don't see it as pointless.  I find it very helpful in gainting a holistic
view of the individual headers, and believe that once I have the entire
collection extracted and properly arranged, it will serve as a means of
gaining a similar holistic view of the entire library.

>> I never said documentation has no role to play in communicating
>> programmer intent.
>
> No, but you did suggest, mistakenly in my opinion, that it would be
> helpful to collect all of the examples of standard header source code
> from the standard into one location.

No.  There are examples, and there are required decalrations and definitions
(which makes extracting the required sections all the more tricky.) Though
parameter names are subject to modification by the implementor, the
presence of the declarations and definitions is not optional.

> I don't see any advantage from
> that, unless the result would be a complete declaration for the
> corresponding section of the standard library. However, in order to
> gain that advantage, it must also possess the disadvantages I've been
> describing.

Can you please provide a concrete example where this would be misleading to
the user?

IMO, it would be helpful to the Standard Committee to see the API they have
actually created, stripped of all "clutter".  There is no question in my
mind as to whether an API should facilitate use and understanding in its
design.  It should.  If you cannot look at the Standard Library API and
feel confident that it communicates its functionality to the programmer
with reasonable effectiveness, you should probably carfully examine why
that is, and determine if that deficiency could be eradicated.

To take another example from Java; from the experienced user's perspective
this is (very) useful:

[javap -private will show all method declarations and members]

$ javap java.lang.System
Compiled from "System.java"
public final class java.lang.System extends java.lang.Object{
    public static final java.io.InputStream in;
    public static final java.io.PrintStream out;
    public static final java.io.PrintStream err;
    public static void setIn(java.io.InputStream);
    public static void setOut(java.io.PrintStream);
    public static void setErr(java.io.PrintStream);
    public static java.nio.channels.Channel inheritedChannel()       throws
java.io.IOException;
    public static void setSecurityManager(java.lang.SecurityManager);
    public static java.lang.SecurityManager getSecurityManager();
    public static native long currentTimeMillis();
    public static native long nanoTime();
    public static native void arraycopy(java.lang.Object, int,
java.lang.Object, int, int);
    public static native int identityHashCode(java.lang.Object);
    public static java.util.Properties getProperties();
    public static void setProperties(java.util.Properties);
    public static java.lang.String getProperty(java.lang.String);
    public static java.lang.String getProperty(java.lang.String,
java.lang.String);
    public static java.lang.String setProperty(java.lang.String,
java.lang.String);
    public static java.lang.String clearProperty(java.lang.String);
    public static java.lang.String getenv(java.lang.String);
    public static java.util.Map getenv();
    public static void exit(int);
    public static void gc();
    public static void runFinalization();
    public static void runFinalizersOnExit(boolean);
    public static void load(java.lang.String);
    public static void loadLibrary(java.lang.String);
    public static native java.lang.String mapLibraryName(java.lang.String);
    static java.lang.Class getCallerClass();
    static {};
}

In some cases it is more effective in providing the information a programmer
wants than is looking at the corresponding API documentation:

http://java.sun.com/j2se/1.5.0/docs/api/java/lang/System.html

There is no doubt in my mind that many C++ programmers believe that C++ *.hh
(or *.h or *.h++ or *.hxx or *.*) header files should contain an interface
to the implementation which is stored in "source" files.  This interface
is, for C++ classes, almost identical to what is provided by the javap
command for Java classes.  The main differences are that C++ class
definitions may hold function definitions (as opposed to function
declarations) or may have inline functions which are typically defined in
the same header file as the class.  Namespace local entities have no
counterpart in Java, but do not represent a significant deviation from the
concept expressed by the analogy.

>> function object for subtraction, etc.  The case in point was Chapter 8,
>> and
>> the discussion of mem_fun verses mem_fun_t.  Until I actually looked at
>> the implementation, it was not clear to me that the former represents a
>> function while the latter represents a function object.
>
> This is not meant as a criticism, I just want to understand the
> context: what had your thoughts about mem_fun_t and mem_fun been,
> before you looked at the implementation?

I didn't really have a very concrete idea, but I was inclined to understand
mem_fun to be a function object.  Not a function.  I'm not sure I had even
recognized that there was a significant distinction between mem_fun and
mem_fun_t.  I will confess to having given Chapter 18 of TC++PL merely a
cursory reading, and have not had a chance to reread it.  At the time, it
seemed wiser to gain a general understanding of what was being provided,
and put off deeper study until I gained more experience with C++.

One observation I will make regarding the usefulness and wisdome of studying
a Standard Library implementation as a means of learning to use C++ in
general, that is basically the approach Stroustrup uses in TC++PL(SE).  He
explicitly states that he intents to use possible implementations of parts
of the Standard Library as a source of example for using C++.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

>>>> And which of these authors told you that the proper way to understand
>>>> an API is to read the header(s) by which it is implemented?
>>>
>>> Bjarne Stroustrup
>>
>> Did he? Where? Please quote a paragraph and page number. Thank you.
>
> Read the book.

Your the one claiming that Bjarne supports your claim.
The 3rd edition is a huge book.
Finding even one sentence that supports what you say is a huge task.
You _must_ be able to point to a particular chapter, paragraph, pages.
General hand waving won't do here.

Stephen Howe


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Stephen Howe wrote:

>> Clearly, he thinks in terms of actual header files, as do many C++
>> programmers.  If the C++ Standard Committee cannot produce the Standard
>> Headers in the form of C++ source code as a means of declaring the API to
>> the Standard Library, how can they, or anybody, reasonably expect that
>> others should produce such interfaces for their libraries?
>
> Suppose it was as you said and that C++ standard did contain model header
> files.
> Would you expect C++ vendors to produce header files identical to the
> standard even if it meant it was sub-optimal for the platform the vendors
> were targeting?

No.  My suggestion only covers presentation of the specification, not what
is specified. The fact of the matter is the Standard /does/ contain the
same content I am suggesting be put in these files.  They don't even need
to be files.  They could very well be sections in an annex.  I do believe
that C++ should enable an implementor to use header files very similar to
the resulting model files. If this is not possible, it probably represents
a deficiency in either the language, or the library specification.

What I am suggesting might be viewed as a counterpart to the grammar in
Annex A.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:

> I don't use KDevelop very much these days either. I use Emacs.  But I
> believe you have just identified the main motivation for objecting to my
> suggestion.  My suggestion would even the playing field and reduce
> artificial barriers to entry.

Which playing field are you talking about, specifically? No matter how I
try to interpret this, this seems a grossly unfair accusation to me.

~Marc.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hyrosen@mail.com (Hyman Rosen)  wrote on 30.06.05 in <20050630192937.D98B7114094@mscan6.ucar.edu>:

> Steven T. Hatton wrote:

> > There is a reasonable expectation that the Standad should be accessible as
> > a reference to the language.

I certainly agree. This has been true for most language standards I have
read; C++ seems to be in a minority here. Even Algol68, while the language
definition itself is insanely hard to understand (though I believe I
finally managed to), has a very accessible standard library definition.
(Accessible enough to find a problem, which in C terms would be to return
a pointer to alloca()d storage).

In any case, when you're in doubt if your tutorial book, your other
tutorial book, the implementation you're using, the different
implementation your friend is using, or none of them is correct wrt. some
feature, then you *need* to use the language standard as a reference -
there just is no substitute.

The C standard manages to do this just fine.

> the authors. It could be chatty like C and C++ or insanely formal
> like Algol 68. In any case, it is meant as a precise description

We're actually asking for a formal bit, here. Something like C99 appendix
B. (I see that some other appendices might also be useful additions.)


In general, my strongly held belief is that everyone who does significant
work in a language, should have the standard for that language available
to check if questions arise, and for that to work, standards need to be
written in such a way as to be accessible *as references* by these people
- *not* just by experts, who, as we have seen repeatedly on these
newsgroups, often enough will not agree to what the standard implies
anyway.

Kai
--
http://www.westfalen.de/private/khms/
"... by God I *KNOW* what this network is for, and you can't have it."
  - Russ Allbery (rra@stanford.edu)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

bop@gmb.dk (Bo Persson)  wrote on 27.06.05 in <3i8uu8Fj6o4oU1@individual.net>:

> But they wouldn't be useful in that form, because they wouldn't compile
> anyway.

What a strange definition of usefulness.

Kai
--
http://www.westfalen.de/private/khms/
"... by God I *KNOW* what this network is for, and you can't have it."
  - Russ Allbery (rra@stanford.edu)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Hyman Rosen wrote:

> Steven T. Hatton wrote:
>> In particular it is inconsistent with what is written
>> in TC++PL(SE) in the sections I've already cited.
>
> Perhaps you missed page 434?
>      "In general, implementers use standard headers in ways
>       programmers cannot predict and shouldn't have to know
>       about."

No.  I simply read the whole paragraph, and understood the context of the
statement.

>> There is a reasonable expectation that the Standad should be accessible
>> as a reference to the language.
>
> The only expectation is that the Standard correctly and completely
> dexcribes the language it is specifying. The style of it is up to
> the authors.

And it is reasonable to expect the authors would want to communicate their
ideas in a way that is accessible as possible without compromising
precision and brevity.  I would at least expect they would want the
document to be accessible to authors who which to write textbooks or
articles about the language.

> It could be chatty like C and C++ or insanely formal
> like Algol 68. In any case, it is meant as a precise description
> for implementors, who are already assumed to be knowledgable in
> the nuances of the language.

How can anyone be knowledgable in the nuances of language features which are
not yet implemented?

>> Being able to view the entire API in the form
>> of class (template) definitions and function declarations cannot be
>> substituted by providing books about using it.
>
> You really must find better books.

I don't understand.  As I have stated above, books are not going to address
the issue.  Here is a perfect example of how having the declarations in a
plain text file so that I can view them in an Emacs buffer is superior to
having them in hardcopy, or in PDF.  I just copied these declarations to an
Emacs buffer after carefully examining them to try to find what differs
between the first and second declarations.  In PDF form I did not notice
the difference because there is no syntax highlighting, and they were not
formatted so that parameter lists were each on a single line.  As soon as I
reformatted the text, I saw immediately what differed between the
declarations.


template<class charT, class traits>
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
charT c);

template<class charT, class traits>
  basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
char c);

>> This is a major reason for
>> having such features as introspection which are core to both Java and C#.
>
> Introspection is for programs to use, not people. It's so that
> general purpose code can deal with objects whose types are not
> compiled into the program. Certainly Java's introspection does
> not involve creating a Java source code file!

And it is used extensively in such tools as IDEs where it is useful to
insert function calls, interface declarations, etc.  I was technically
mistaken about javap actually using reflection.  The many examples on the
internet of using reflection (AKA introspection) to implement the same
functionality as javap explain that javap is actually a bytecode
disassembler. Introspection can be used to provide such features as class
browsers, code completion, UML diagrams, edit-time error checking,
interactive activation stack browsing in debuggers, property list dialogs,
GUI builders etc.  And yes, these GUI builders often do create the
sourcecode. (sometimes they produce XML which is later converted into
source code.)

>> You can query a library and have it programmatically provide its public
>> interface, or in some cases even more.  That feature is one of the
>> biggest reason Java is easier to learn than C++.
>
> This is certainly a unique point of view. I assure you that there is
> no one in the world, except perhaps you, who learns how to program a
> library by querying its interfaces programmatically. The most basic
> reason is that doing so gives you no information about the semantics
> of the interfaces you are discovering.

First of all, I never said I use the feature exclusively.  Secondly, I know
java programmers who code in vi and rely heavily on using javap to view the
interfaces.  Tell me, how do you think you would set a given element in a
Java java.util.ArrayList?  Remove it? Convert the ArrayList to a Java
Array? Determine if the ArrayList is empty?  Find the size of the
ArrayList?  Find the index of a given element?


public class java.util.ArrayList extends java.util.AbstractList implements
java.util.List,java.util.RandomAccess,java.lang.Cloneable,java.io.Serializable{
    public java.util.ArrayList(int);
    public java.util.ArrayList();
    public java.util.ArrayList(java.util.Collection);
    public void trimToSize();
    public void ensureCapacity(int);
    public int size();
    public boolean isEmpty();
    public boolean contains(java.lang.Object);
    public int indexOf(java.lang.Object);
    public int lastIndexOf(java.lang.Object);
    public java.lang.Object clone();
    public java.lang.Object[] toArray();
    public java.lang.Object[] toArray(java.lang.Object[]);
    public java.lang.Object get(int);
    public java.lang.Object set(int, java.lang.Object);
    public boolean add(java.lang.Object);
    public void add(int, java.lang.Object);
    public java.lang.Object remove(int);
    public boolean remove(java.lang.Object);
    public void clear();
    public boolean addAll(java.util.Collection);
    public boolean addAll(int, java.util.Collection);
    protected void removeRange(int, int);
}

>> Please review the previous conversation on this matter.
>  > The meaning of my comments should then be clear to you.
>
> It's clear enough to me that such an implementationless
> implementation would be worse than useless, by needlessly
> overconstraining library authors.

They would not have any content that is not found in the body of the
Standard other than commented text pointing back to the body of the
Standard at the location where the particular items are introduced.

>> That is your opinion.  In my opinion, you are describing
>> a very bad way of providing an API.
>
> But since this is how virtually all APIs are provided,
> it would appear that my opinion is the one used, while
> yours is not. Another way of saying this is that your
> opinion is wrong.

http://www.kdevelop.org/HEAD/doc/api/html/codemodel_8h-source.html
http://unstable.elemental.com/mozilla/build/latest/mozilla//embedding/dox/qa_2testembed_2BrowserImpl_8h.html
The same location as a tinyurl
http://tinyurl.com/a3fjt

http://xml.apache.org/xerces-c/apiDocs/files.html

http://www.openscenegraph.org/documentation/OpenSceneGraph/include/
"Use the source Luke".

>> I did not write implementation.  I wrote "as a means of _declaring_ the
>> API to the Standard Library".
>
> That is part of the implementation. Declarations of types and
> functions are a part of the implementation.

And they must faithfully follow the declarations in the C++ Standard if they
are to be compliant.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Hyman Rosen wrote:
>
> > Steven T. Hatton wrote:
.
> > It could be chatty like C and C++ or insanely formal
> > like Algol 68. In any case, it is meant as a precise description
> > for implementors, who are already assumed to be knowledgable in
> > the nuances of the language.
>
> How can anyone be knowledgable in the nuances of language features which are
> not yet implemented?

In general, something shouldn't be canonized in the standard until
after it's actually been implemented somewhere; but admittedly that
goal has often not been. I can't say about the other languages, but for
C++ most of the language, and a large part of what is now the standard
library, had been implemented long before the first version of the
standard was approved. In this context, his comment about being
"knowledgable in the nuances of the language" must be understood as
being knowledgeable about the nuance of the already existing language,
and therefore well prepared to understand how the new standard differs
from it.

I think the standard should be understandable by anyone who is
sufficiently competent to implement the language, even if they have
never actually done so before. While it describes what is, in essence,
a contract between users and developers, I don't think it's appropriate
to require it to be written to be understandable to all users. New
users can be arbitrarily dumb, and requring that the language of the
standard be dumbed down to the point where it would be understandable
to everyone would tend to discourage the committee from specifying
features that are too complicated for entry level programmers to use.
There's a niche for languages that simple, but it's not the niche that
C++ is intended to occupy.

I'm not suggesting that you've asked for such a change; merely
providing a context for explaining my attitudes about the proper level
of the presentation of the C++ standard.

.
> I don't understand.  As I have stated above, books are not going to address
> the issue.  Here is a perfect example of how having the declarations in a
> plain text file so that I can view them in an Emacs buffer is superior to
> having them in hardcopy, or in PDF.  I just copied these declarations to an
> Emacs buffer after carefully examining them to try to find what differs
> between the first and second declarations.  In PDF form I did not notice
> the difference because there is no syntax highlighting, and they were not
> formatted so that parameter lists were each on a single line.  As soon as I
> reformatted the text, I saw immediately what differed between the
> declarations.
>
>
> template<class charT, class traits>
>   basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
> charT c);
>
> template<class charT, class traits>
>   basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>& out,
> char c);

To each his own; in the original PDF the distinction looks pretty clear
to me. Each character of the second declarations is presented
vertically aligned with the corresponding character of the first
declaration, right up to the point where there is no corresponding
character in the second declaration. I can see syntax highlighting as a
valuable thing, but there's no good reason why the PDF couldn't have
syntax highlighting, too.

.
> They would not have any content that is not found in the body of the
> Standard other than commented text pointing back to the body of the
> Standard at the location where the particular items are introduced.

You've suggested elsewhere that they should be complete; which headers
limited in the fashion you describe above would not be. The result
could not be compiled as if it were actually the required standard
header.

.
> > That is part of the implementation. Declarations of types and
> > functions are a part of the implementation.
>
> And they must faithfully follow the declarations in the C++ Standard if they
> are to be compliant.

Those declarations must conform to the requirements of the C++
standard, including those requirements that are conveyed in the form of
example source code for header files. However, they don't have to match
the sample source code; they can use any other code that they wish, so
long as all well-formed programs that #include those headers will have
observable behavior that is consistent with the standard's
specifications when translated and executed by that implementation.

Note: examination of the contents of the header is not covered by the
"observable behavior" rule.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
>
> > "Steven T. Hatton" wrote:
> >> kuyper@wizard.net wrote:
.
> > I don't see any advantage from
> > that, unless the result would be a complete declaration for the
> > corresponding section of the standard library. However, in order to
> > gain that advantage, it must also possess the disadvantages I've been
> > describing.
>
> Can you please provide a concrete example where this would be misleading to
> the user?

Consider std::basic_string<charT,traits,Allocator>::iterator.
According to the standard, this type is implementation-defined. The
type chose by one implementation might be incompatible with the type
chose by another implementation. In code that is intended to be
portable, the only safe thing to do is to refer to that type through
that typedef. A reader seeing that particular typedef might assume that
it's required by the standard, rather than being specific to that
particular implementation. You can't create a non-committal standard
header file that leaves that typedef unspecified and have it actually
be compileable. You can surround the typedef with comments that
indicate that the particular type used is just an example, and that the
actual type is implementation-defined; you can hope that the reader
will notice and understand those comments. However, I've noticed a
tendency of many programmers to ignore comments and just read the code;
the motivation for that tendency is much the same as the motivation for
your suggestion.

This isn't just one problem: the same issue applies to every single
implementation-defined aspect of the C++ standard library's API. Adding
enough comments to cover all those issues would bring you to the point
where it's simpler and more appropriate to just read the standard
itself, with it's embedded header source code, than to read the source
code alone.

> I didn't really have a very concrete idea, but I was inclined to understand
> mem_fun to be a function object.  Not a function.  I'm not sure I had even
> recognized that there was a significant distinction between mem_fun and
> mem_fun_t.

I'm having trouble understanding how you could be aware of both names,
and not recognise the crucial distinction: mem_fun_t is the return type
of mem_fun(). I don't see a header file as necessary for understanding
that distinction. Any discussion of mem_fun and mem_fun_t must include
code that makes it clear either that mem_fun() is a function, or that
mem_fun_t is a type; though it might not make both facts clear in the
same part of the discussion.

I can understand not understanding what a function object is; I've had
the fun of trying to explain that to several C++ newbies, and for some
of them it's a very tricky concept. But you won't resolve that
confusion by looking at a declaration for mem_fun().

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> Stephen Howe wrote:
>>
>> >>> And which of these authors told you that the proper way to understand
>> >>> an API is to read the header(s) by which it is implemented?
>> >>
>> >> Bjarne Stroustrup
>> >
>> > Did he? Where? Please quote a paragraph and page number. Thank you.
>>
>> Read the book.
>
> I have. Didn't see it. If it was there, and I missed it, and you claim
> to have seen it, it helps your case enormously if you can tell me
> where.
>
> When you make a claim about a book that is in conflict with my memory
> of that book, I'm entitled to assume that your refusal to provide a
> more specific citation is because you can't provide one.

It's pervasive and relies on certain assumptions about programming which I
hold to be axiomatic.  Among these assumptions is that the primary reason
for creating programming languages is to facilitate human-to-human (and
that can be understood selfreferentially) communication while at the same
time preparing a set of instructions to be automatically executed by a
computer.

For an exact citation quoted from the text of TC++PL(SE) please review this
thread from the beginning.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:
> In this context, his comment about being "knowledgable in the nuances
 > of the language" must be understood as being knowledgeable about the
 > nuance of the already existing language, and therefore well prepared
 > to understand how the new standard differs from it.

It's not just that. Another thing that's not at all unusual for a
standard is that the requirements for some particular feature can
be scattered throughout the document, and a seemingly innocuos
phrase in one part can have deep impact. Someone who comes naiively
to the Standard will not realize this until it's too late.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Kai Henningsen wrote:

> hyrosen@mail.com (Hyman Rosen)  wrote on 30.06.05 in
> <20050630192937.D98B7114094@mscan6.ucar.edu>:

>> the authors. It could be chatty like C and C++ or insanely formal
>> like Algol 68. In any case, it is meant as a precise description
>
> We're actually asking for a formal bit, here. Something like C99 appendix
> B. (I see that some other appendices might also be useful additions.)
>
>
> In general, my strongly held belief is that everyone who does significant
> work in a language, should have the standard for that language available
> to check if questions arise, and for that to work,

I find the C++ Standard to be written in almost lawyerly terms.  Part of
that is understandable.  There is an effort made to be precise in what it
does specify, and avoid specifying anything that might unnecessarily
restrict an implementation. It also seems to be the result of many
"patches" added to the original without a great deal of concern for the
overall readability.  I'm certainly not suggesting it be made anywhere near
as hand-holdy as the C# standard. Parts of the C++ Standard are actually
fairly readable. Clause 3 was like wandering through an intellectual
labyrinth.  The clauses specifying classes, OTOH, are some of the most
accessible texts I've read on the subject.

> standards need to be
> written in such a way as to be accessible *as references* by these people
> - *not* just by experts, who, as we have seen repeatedly on these
> newsgroups, often enough will not agree to what the standard implies
> anyway.

There's a good chance that the difficult form of the Standard could make
implementation more difficult than it needs to be.  I don't really know how
to improve the wording and organization of the whole document.  That would
truly be a significant task. One suggestion I made about a year ago was to
take the entire document print it out single-sided, pin all the pages up on
a big pegboard and pin strings to it connecting all the internal
references.  I wish I had it in XML form.  I can think of a lot of ways of
manipulating it to examine its structure, and to extract different types of
information from it.

I believe it's too much to ask of the Standard Committee, but an annotated
version of the grammar would be nice to have available.  Something that
provided references back into the body of the document, and also some
example code with markup of some kind to identify the grammatical
decomposition.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Hyman Rosen wrote:
> kuyper@wizard.net wrote:
> > In this context, his comment about being "knowledgable in the nuances
>  > of the language" must be understood as being knowledgeable about the
>  > nuance of the already existing language, and therefore well prepared
>  > to understand how the new standard differs from it.
>
> It's not just that. Another thing that's not at all unusual for a
> standard is that the requirements for some particular feature can
> be scattered throughout the document, and a seemingly innocuos
> phrase in one part can have deep impact. Someone who comes naiively
> to the Standard will not realize this until it's too late.

I know what you mean. I remember a mistake I made when I was new to the
C++ standard, by assuming that "aggregate type" was ordinary English,
rather than a specific piece of jargon defined by the standard. As a
result, I missed a rather important piece of specification that applies
to POD types, because that specification was connected to POD types
only through the use of the term "aggregate type". I searched for all
occurances in the standard of "POD", but didn't think to search for
"aggregate" as well.

Another example is the significance of null pointer constants. Their
real significance is due the fact that in certain contexts they get
treated as null pointer values, rather than as integers. That fact is
scattered in many different parts of the standard, rather than being
explained in the section that defines a null pointer constant.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> Stephen Howe wrote:
>
> >> Clearly, he thinks in terms of actual header files, as do many C++
> >> programmers.  If the C++ Standard Committee cannot produce the Standard
> >> Headers in the form of C++ source code as a means of declaring the API to
> >> the Standard Library, how can they, or anybody, reasonably expect that
> >> others should produce such interfaces for their libraries?
> >
> > Suppose it was as you said and that C++ standard did contain model header
> > files.
> > Would you expect C++ vendors to produce header files identical to the
> > standard even if it meant it was sub-optimal for the platform the vendors
> > were targeting?
>
> No.  My suggestion only covers presentation of the specification, not what
> is specified. The fact of the matter is the Standard /does/ contain the
> same content I am suggesting be put in these files.  They don't even need
> to be files.  They could very well be sections in an annex.  I do believe
> that C++ should enable an implementor to use header files very similar to
> the resulting model files. If this is not possible, it probably represents
> a deficiency in either the language, or the library specification.
>
> What I am suggesting might be viewed as a counterpart to the grammar in
> Annex A.

Then why don't you _do_ it? This thread's been going on for over a week
now; if you had used that time instead to collect and organize the
content, you could be well on your way to a formal proposal. Instead,
you're still decribing the problem and the solution as if someone else
should do the work for you.

Do the work, post it somewhere, and we'll have something concrete to
discuss. If you're unwilling to do this (and the evidence of this
thread suggests that you are unwilling), it undermines both the
importance you attach to the problem as well as the necessity of the
solution you propose.

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Kai Henningsen" <kaih=9$6Kubzmw-B@khms.westfalen.de> skrev i
meddelandet news:9$6Kubzmw-B@khms.westfalen.de...
> bop@gmb.dk (Bo Persson)  wrote on 27.06.05 in
> <3i8uu8Fj6o4oU1@individual.net>:
>
>> But they wouldn't be useful in that form, because they wouldn't
>> compile
>> anyway.
>
> What a strange definition of usefulness.

The other poster wanted the standards committee to produce a set of
reference C++ headers for the standard library. To make the templates in
the headers compile, some headers must include others headers. The
standard explicitly states that it is unspecified which headers include
each other. That is left as an implementation detail.

This makes it impossible for the standard committee to produce such
headers, without specifying one specific order anyway. That would then
be the One and Only True Way, especially if we use it as a set of
reference headers documenting the API.


If not complete, what good use is there for a set of C++ headers that
can't even be compiled?


Bo Persson


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> kuyper@wizard.net wrote:
>>
>> > "Steven T. Hatton" wrote:
>> >> kuyper@wizard.net wrote:
> .
>> > I don't see any advantage from
>> > that, unless the result would be a complete declaration for the
>> > corresponding section of the standard library. However, in order to
>> > gain that advantage, it must also possess the disadvantages I've been
>> > describing.
>>
>> Can you please provide a concrete example where this would be misleading
>> to the user?
>
> Consider std::basic_string<charT,traits,Allocator>::iterator.
> According to the standard, this type is implementation-defined. The
> type chose by one implementation might be incompatible with the type
> chose by another implementation. In code that is intended to be
> portable, the only safe thing to do is to refer to that type through
> that typedef. A reader seeing that particular typedef might assume that
> it's required by the standard, rather than being specific to that
> particular implementation. You can't create a non-committal standard
> header file that leaves that typedef unspecified and have it actually
> be compileable.

I never said these should be compilable.  It's nice to have them parse
correctly.  For that I did this:

typedef implementation_defined_const_list_iterator  const_iterator;

But for my suggestion the annex could just as well leave the line as:
typedef implementation defined  const_iterator;

There are (IIRC) 36 places where an iterator is presented in this way.
There are a few other places were the implementation must provide a
definion.  It took me a bit of contemplation to realize exactly what was
going on in <ios> with T1, T2, T3 and T4.  Now I understand both what is
there, and why it is there.  Understanding /what/ these identifiers implied
took, perhaps 30 seconds.  Understanding why didn't happen until I read the
section in TC++SL.  Anybody who can't figure out that "implementation
defined" means that it is defined by the implementation is probably not
qualified to be working with C++.  And for myself, I will admit, when I
encountered them, I found those particular pseudo-typedefs to be confusing
in exactly how they impacted the implementation.

That was more due to the fact that I didn't understand C++ well enough at
the time.

> You can surround the typedef with comments that
> indicate that the particular type used is just an example, and that the
> actual type is implementation-defined; you can hope that the reader
> will notice and understand those comments. However, I've noticed a
> tendency of many programmers to ignore comments and just read the code;
> the motivation for that tendency is much the same as the motivation for
> your suggestion.

To save time, and think in terms of the code itself, rather than the
documentation is a good quality.  In one of the projects I'm working with,
"Use the source Luke" is the explicit suggestion of the lead developer.  In
another, the code is written by people from several different countries who
do not speak a commen language other than C++.  Trust me, there are times
when I would like a few comments, and there are none.  There are times when
my limited ability to read German comes in handy.

> This isn't just one problem: the same issue applies to every single
> implementation-defined aspect of the C++ standard library's API. Adding
> enough comments to cover all those issues would bring you to the point
> where it's simpler and more appropriate to just read the standard
> itself, with it's embedded header source code, than to read the source
> code alone.

There really aren't that many places where this is an issue.  If you really
want a sense of the frequency of these "implementation defined" items, may
I suggest you extract the declarations for entities which the Standard
requires be provided by the Standard Headers, and place these declarations
in text files named to reflect the respective headers?  I have found the
result very useful.  As I read through Josuttis's book, I frequently return
to these declaration files to see exactly what the primary topic of his
800-page book actually looks like.

>> I didn't really have a very concrete idea, but I was inclined to
>> understand
>> mem_fun to be a function object.  Not a function.  I'm not sure I had
>> even recognized that there was a significant distinction between mem_fun
>> and mem_fun_t.
>
> I'm having trouble understanding how you could be aware of both names,
> and not recognise the crucial distinction: mem_fun_t is the return type
> of mem_fun(). I don't see a header file as necessary for understanding
> that distinction. Any discussion of mem_fun and mem_fun_t must include
> code that makes it clear either that mem_fun() is a function, or that
> mem_fun_t is a type; though it might not make both facts clear in the
> same part of the discussion.

Perhaps I should have gleaned that from the discussion.  I wrote to the
author and explained my confusion, and suggested he try to make it more
clear in any future edition.  Bear in mind that such concepts as the
distinction between function and function object in such a context can be
rather nebulous to an inexperienced reader.  Be that as it may, when I
looked at this it all became clear:

template <class _Ret, class _Tp>
class mem_fun_t : public unary_function<_Tp*,_Ret> {
public:
  explicit mem_fun_t(_Ret (_Tp::*__pf)()) : _M_f(__pf) {}
  _Ret operator()(_Tp* __p) const { return (__p->*_M_f)(); }
private:
  _Ret (_Tp::*_M_f)();
};

//...
template <class _Ret, class _Tp>
inline mem_fun_t<_Ret,_Tp> mem_fun(_Ret (_Tp::*__f)())
  { return mem_fun_t<_Ret,_Tp>(__f); }

You can argue that I should have looked at the documentation for the
implementation I'm using.  Well, that would give me this:
http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/stl__function_8h-source.html

> I can understand not understanding what a function object is; I've had
> the fun of trying to explain that to several C++ newbies, and for some
> of them it's a very tricky concept. But you won't resolve that
> confusion by looking at a declaration for mem_fun().

I'm not sure what point you are trying to make.  Mind you, this example from
my experience was meant to address the broader issue of whether it is
useful to read your standard headers. I provided an example from my own
experience in which that was indeed useful.  I have provided other examples
of where the files I have created based on the content of the Standard have
been useful to me.  These files are useful to me.  You are not in a
position to assess that assertion.  The best you can do is consider whether
they would be useful to others, and whether that usefulness would add
sufficient value to the Standard document to justify their inclusion.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

kuyper@wizard.net wrote:

> "Steven T. Hatton" wrote:
>> Hyman Rosen wrote:
>>
>> > Steven T. Hatton wrote:
> .
>> > It could be chatty like C and C++ or insanely formal
>> > like Algol 68. In any case, it is meant as a precise description
>> > for implementors, who are already assumed to be knowledgable in
>> > the nuances of the language.
>>
>> How can anyone be knowledgable in the nuances of language features which
>> are not yet implemented?
>
> In general, something shouldn't be canonized in the standard until
> after it's actually been implemented somewhere; but admittedly that
> goal has often not been. I can't say about the other languages, but for
> C++ most of the language, and a large part of what is now the standard
> library, had been implemented long before the first version of the
> standard was approved. In this context, his comment about being
> "knowledgable in the nuances of the language" must be understood as
> being knowledgeable about the nuance of the already existing language,
> and therefore well prepared to understand how the new standard differs
> from it.

The fact of the matter is that I believe that approach is flawed, though it
may not be fully correctable.  The Standard should specify the language and
libraries in such a way as to be self-contained in the mathematical sense.
Ideally a person with a substantial background in computer science should
be able to use the standard to implement C++ whether he or she has ever
programmed in C++.  That may not be 100% achievable, but it should be the
objective.

> I think the standard should be understandable by anyone who is
> sufficiently competent to implement the language, even if they have
> never actually done so before. While it describes what is, in essence,
> a contract between users and developers, I don't think it's appropriate
> to require it to be written to be understandable to all users.

I never suggested that it should be.  I suggested that it should be more
accessible as a reference.  I gave an example of where wording was clearly
misleading to a person who was trying to get an overview of the particular
clause in question.  If I were an implementor, I would probably take a very
similar approach to the one I took in approaching that clause.

> New
> users can be arbitrarily dumb, and requring that the language of the
> standard be dumbed down to the point where it would be understandable
> to everyone would tend to discourage the committee from specifying
> features that are too complicated for entry level programmers to use.
> There's a niche for languages that simple, but it's not the niche that
> C++ is intended to occupy.

The last time I did a job search based on my skillset, what I found were
positions for people porting legacy C++ code to Java.  What's wrong with
C++?  It's too hard to learn, and the code can be too difficult to
understand so that it can be maintained.

Is that an inherent flaw in C++?  For the most part, I will say no.  Is it
an inherent flaw in the C++ community?

> I'm not suggesting that you've asked for such a change; merely
> providing a context for explaining my attitudes about the proper level
> of the presentation of the C++ standard.

I'm glad you have qualified your statement. It gives me confidence that
someone is actually paying attention to what I've really suggested.

>> template<class charT, class traits>
>>   basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&
>>   out,
>> charT c);
>>
>> template<class charT, class traits>
>>   basic_ostream<charT,traits>& operator<<(basic_ostream<charT,traits>&
>>   out,
>> char c);
>
> To each his own; in the original PDF the distinction looks pretty clear
> to me.

I have to wonder what it would have looked like to you if you had approached
it from the same perspective as I did.  I might expect a textbook author to
take a very similar approach to that which I took in studying the
declarations.

> Each character of the second declarations is presented
> vertically aligned with the corresponding character of the first
> declaration, right up to the point where there is no corresponding
> character in the second declaration. I can see syntax highlighting as a
> valuable thing, but there's no good reason why the PDF couldn't have
> syntax highlighting, too.

Another suggestion I would have presented, had my first not met with so much
resistance.

>> They would not have any content that is not found in the body of the
>> Standard other than commented text pointing back to the body of the
>> Standard at the location where the particular items are introduced.
>
> You've suggested elsewhere that they should be complete; which headers
> limited in the fashion you describe above would not be. The result
> could not be compiled as if it were actually the required standard
> header.

I have explicitly, and repeatedly acknowledged this.  Bear in mind that you
are describing to me what you *think* these files might look like.  I am
looking at them.

>> > That is part of the implementation. Declarations of types and
>> > functions are a part of the implementation.
>>
>> And they must faithfully follow the declarations in the C++ Standard if
>> they are to be compliant.
>
> Those declarations must conform to the requirements of the C++
> standard, including those requirements that are conveyed in the form of
> example source code for header files. However, they don't have to match
> the sample source code; they can use any other code that they wish, so
> long as all well-formed programs that #include those headers will have
> observable behavior that is consistent with the standard's
> specifications when translated and executed by that implementation.

And that behavior can be stated in terms of the declarations I have
described.  Basically the what is specified is that a program that
#includes a given Header shall behave as if these declarations were
present, and implemented as described in the Standard.  I am not even
suggesting such wording be included in the suggested Annex.

> Note: examination of the contents of the header is not covered by the
> "observable behavior" rule.

And what has that to do with the subject at hand?
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") writes:

>>> I did not write implementation.  I wrote "as a means of _declaring_ the
>>> API to the Standard Library".
>>
>> That is part of the implementation. Declarations of types and
>> functions are a part of the implementation.
>
> And they must faithfully follow the declarations in the C++ Standard if they
> are to be compliant.

Actually, no.  They just have to be indistinguishable from the POV of
a correct, portable program.  There lots of well-known ways to have
the declarations differ substantially.  For one trivial example, an
implmentation can add parameters to any (member) function or class
template as long as the parameters have default values.

--
Dave Abrahams
Boost Consulting
www.boost-consulting.com

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:
> And so what _is_ required of the implementation in order to provide the
> correct behavior when #include <iostream> is added to C++ code?

Merely that when it encounters that sequence in a compilation unit,
the types, declarations, and macros required by the Standard become
available for subsequent use in that unit. Since the names of the
standard headers are standard, an implementation may simply have
"canned" data structures that it can incorporate when it encounters
one.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Steven T. Hatton" wrote:
> kuyper@wizard.net wrote:
>
> > "Steven T. Hatton" wrote:
> >> Stephen Howe wrote:
> >>
> >> >>> And which of these authors told you that the proper way to understand
> >> >>> an API is to read the header(s) by which it is implemented?
> >> >>
> >> >> Bjarne Stroustrup
> >> >
> >> > Did he? Where? Please quote a paragraph and page number. Thank you.
> >>
> >> Read the book.
> >
> > I have. Didn't see it. If it was there, and I missed it, and you claim
> > to have seen it, it helps your case enormously if you can tell me
> > where.
> >
> > When you make a claim about a book that is in conflict with my memory
> > of that book, I'm entitled to assume that your refusal to provide a
> > more specific citation is because you can't provide one.
>
> It's pervasive

I might have missed a line or two, but if it were pervasive, I'm pretty
sure I would remember it. Bjarne mentions header files in very specific
places, and in none of them do I recall a recommendation that users
read them to understand the APIs they contain.

> and relies on certain assumptions about programming which I
> hold to be axiomatic.

Now you're saying that the meaning of the book depends on your
assumptions?

> Among these assumptions is that the primary reason
> for creating programming languages is to facilitate human-to-human (and
> that can be understood selfreferentially) communication while at the same
> time preparing a set of instructions to be automatically executed by a
> computer.

Among my assumptions is that code is more appropriate for
human-to-computer communication than human-to-human; the human-to-human
thing must be a secondary consideration, since there are already
natural languages that fit this bill. It's therefore no surprise that
API documentation tends to be written in natural languages. Further, if
code were an appropriate domain for human-to-human communication, there
would be no need for comments.

> For an exact citation quoted from the text of TC++PL(SE) please review this
> thread from the beginning.

I (and others, it seems) have examined your citations and found them to
be ambiguous at best. If you're so sure you're right, please post
unambiguous citations.

Bob

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Hyman Rosen wrote:

> Steven T. Hatton wrote:
>> And so what _is_ required of the implementation in order to provide the
>> correct behavior when #include <iostream> is added to C++ code?
>
> Merely that when it encounters that sequence in a compilation unit,
> the types, declarations, and macros required by the Standard become
> available for subsequent use in that unit. Since the names of the
> standard headers are standard, an implementation may simply have
> "canned" data structures that it can incorporate when it encounters
> one.

Nonetheless, regardless of how these headers are provided, they must behave
_as_if_ the declarations and definitions specified by the Standard were
explicitly provided.  I'm all for inventive ways of providing such things
as Standard Headers.  I do believe it would make C++ more usable if there
were a common practice of providing the kinds of declarations I am speaking
of, even if they are not "part of the implementation" per se.  For example,
if you store your header implementation in some kind of database that
accepts queries from a CPP and returns instantiated templates, it would
still be desirable to provide the ability to query the db for the
declarations.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

David Abrahams wrote:

> hattons@globalsymmetry.com ("Steven T. Hatton") writes:
>
>>>> I did not write implementation.  I wrote "as a means of _declaring_ the
>>>> API to the Standard Library".
>>>
>>> That is part of the implementation. Declarations of types and
>>> functions are a part of the implementation.
>>
>> And they must faithfully follow the declarations in the C++ Standard if
>> they are to be compliant.
>
> Actually, no.  They just have to be indistinguishable from the POV of
> a correct, portable program.  There lots of well-known ways to have
> the declarations differ substantially.  For one trivial example, an
> implmentation can add parameters to any (member) function or class
> template as long as the parameters have default values.
>

And that implementation would behave differently when presented with
conforming C++ code?  I don't believe there are a significant number of
places where the suggested representative files would require
qualification.  I am aware of the statement in the standard you are
referring to.  I agree, it's trivial.

--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

IMHO the Standard Library declarations will be clearer to read if they
used template parameter names like In, Out, For, Bi, Ran, Pred, etc
(like in TC++PL) instead of rambling names like InputIterator,
OutputIterator, ForwardIterator, BidirectionalIterator,
RandomAccessIterator, Predicate, etcetera.

Prateek
--                                   --
To iterate is human, to recurse divine.
-L. Peter Deutsch
--                                   --

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Prateek" <kprateek88@gmail.com> writes:

> IMHO the Standard Library declarations will be clearer to read if they
> used template parameter names like In, Out, For, Bi, Ran, Pred, etc
> (like in TC++PL) instead of rambling names like InputIterator,
> OutputIterator, ForwardIterator, BidirectionalIterator,
> RandomAccessIterator, Predicate, etcetera.

N my pnion ur pst wd b ezer 2 rd f u used shrthnd lk me.

--
Dv Abrhms
Bst Cnsltng
w3bst-cnsltng.com

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:
> Pete Becker wrote:
>
>
>>Steven T. Hatton wrote:
>>
>>
>>>It seems reasonable to me that the Standard Committee would make the
>>>standard header declarations available in the form that they are
>>>presented in the Standard, but as separate files holding nothing but the
>>>header declarations, and references back to the relevant text in the
>>>Standard.
>>>
>>
>>Volunteering other people to do this work won't get it done. Write it up
>>and propose it.
>
>
> As far as who actually does the work, I would expect the people working on a
> particular part of the Standard would be most qualified to provide the file
> for their particular header.  To a person familiar with given section of
> the Standard associated with a Header, this should constitute about 10
> minutes of work.
>

Then it shouldn't take you much more than 20 minutes to do it. That has
the great advantage that it shows your commitment -- tt's easy to
suggest that other people should do work for you. But then you'll also
be on the hook for maintaining what you've written as the standard
changes. Writing the same thing more than once is expensive.

--

Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

David Abrahams wrote:

> "Prateek" <kprateek88@gmail.com> writes:
>
>
>>IMHO the Standard Library declarations will be clearer to read if they
>>used template parameter names like In, Out, For, Bi, Ran, Pred, etc
>>(like in TC++PL) instead of rambling names like InputIterator,
>>OutputIterator, ForwardIterator, BidirectionalIterator,
>>RandomAccessIterator, Predicate, etcetera.
>
>
> N my pnion ur pst wd b ezer 2 rd f u used shrthnd lk me.
>

<g> But I agree with Prateek in principle: the current names are far too
long. In our documentation we use InIt, OutIt, etc. Otherwise you end up
with really long lines, or you have to break declarations up into
multiple lines, making them harder to read. Not to mention the problems
they cause when you try to typeset a book.

--

Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"David Abrahams" <dave@boost-consulting.com> wrote in message
news:ufyv32436.fsf@boost-consulting.com...
> "Prateek" <kprateek88@gmail.com> writes:
>
>> IMHO the Standard Library declarations will be clearer to read if they
>> used template parameter names like In, Out, For, Bi, Ran, Pred, etc
>> (like in TC++PL) instead of rambling names like InputIterator,
>> OutputIterator, ForwardIterator, BidirectionalIterator,
>> RandomAccessIterator, Predicate, etcetera.
>
> N my pnion ur pst wd b ezer 2 rd f u used shrthnd lk me.

Nevertheless, if such abbreviations were unambiguous and used
*consistently*, and a table was provide up-front which explained what those
abbreviations are, I believe it would increase readability.  (Personally,
I'd use "Fwd" to avoid confusion with the keyword "for".)

I know abbreviations are out of fashion these days, but there can be good
reasons to use them.  Which is easier to use and/or more understandable,
"InstituteOfElectricalAndElectronicsEngineers_WirelessLocalAreaNetwork_MediumAccessController"
or "IEEE_WLAN_MAC"?  After reading and typing it 1000 types, which is
easier?

--
Eric Backus
R&D Design Engineer
Agilent Technologies, Inc.
425-356-6010 Tel

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

""Steven T. Hatton"" <hattons@globalsymmetry.com> skrev i meddelandet
news:jJWdnc3_9Il7UCLfRVn-tg@speakeasy.net...
>Bo Persson wrote:

>> That's because the standard headers contain circularites, that are
>> usually resolved by dividing the files into smaller parts, and
>> including
>> these parts in the required headers.
>>
>> One example is that <string> contains references to <stdexcept> whose
>> classes have string parameters. They would both have to include each
>> other!
>
>No matter how you break it up, you are going to end up doing something
>to
>break the cycle.  I suspect that could be done without braking the
>files
>up.  You may need a little dab of gluecode, but I would very much like
>to
>see an argument for much more than that.


I have more than a suspicion, because I have already tried this. It
didn't work.

You need another example?

In 27.2 <iosfwd> you have

typedef fpos<char_traits<char>::state_type>   streampos;


and in section 21.1.3.1 struct char_traits<char> you have

template<>
struct char_traits<char> {

typedef streampos   pos_type;
typedef mbstate_t   state_type;

};

which poses a similar problem. Will you define streampos or char_traits
first?

There are even more problems of this kind in the standard library. That
is one reason why the actual implementations don't contain literal
copies of the standard document headers.


Bo Persson


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

"Eric Backus" wrote:
> "David Abrahams" <dave@boost-consulting.com> wrote in message
> news:ufyv32436.fsf@boost-consulting.com...
> > "Prateek" <kprateek88@gmail.com> writes:

> >> IMHO the Standard Library declarations will be clearer to
> >> read if they used template parameter names like In, Out,
> >> For, Bi, Ran, Pred, etc (like in TC++PL) instead of
> >> rambling names like InputIterator, OutputIterator,
> >> ForwardIterator, BidirectionalIterator,
> >> RandomAccessIterator, Predicate, etcetera.

> > N my pnion ur pst wd b ezer 2 rd f u used shrthnd lk me.

> Nevertheless, if such abbreviations were unambiguous and used
> *consistently*, and a table was provide up-front which
> explained what those abbreviations are, I believe it would
> increase readability.  (Personally, I'd use "Fwd" to avoid
> confusion with the keyword "for".)

The key is, effectively, that they be used consistently, and
that there use be documented.  I generally avoid abbreviations
myself, but I've settled on FwdIter, BidirIter and RandomIter,
when the template parameter must meet one of these constraints.

> I know abbreviations are out of fashion these days, but there can be good
> reasons to use them.  Which is easier to use and/or more understandable,
> "InstituteOfElectricalAndElectronicsEngineers_WirelessLocalAreaNetwork_MediumAccessController"
> or "IEEE_WLAN_MAC"?  After reading and typing it 1000 types, which is
> easier?

That's a different case entirely, I think.  For most people, the
name of the organization is IEEE (regardless of what its charter
says).  Similarly, LAN is more recognizable than local area
network, and MAC is also an established acronym, with many
people speaking about MAC addresses without having the slightest
idea what the acronym stands for.

--
James Kanze                                           GABI Software
Conseils en informatique orient   e objet/
                   Beratung in objektorientierter Datenverarbeitung
9 place S   mard, 78210 St.-Cyr-l'   cole, France, +33 (0)1 30 23 00 34


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Pete Becker wrote:

> Steven T. Hatton wrote:
>> Pete Becker wrote:
>>
>>
>>>Steven T. Hatton wrote:
>>>
>>>
>>>>It seems reasonable to me that the Standard Committee would make the
>>>>standard header declarations available in the form that they are
>>>>presented in the Standard, but as separate files holding nothing but the
>>>>header declarations, and references back to the relevant text in the
>>>>Standard.
>>>>
>>>
>>>Volunteering other people to do this work won't get it done. Write it up
>>>and propose it.
>>
>>
>> As far as who actually does the work, I would expect the people working
>> on a particular part of the Standard would be most qualified to provide
>> the file
>> for their particular header.  To a person familiar with given section of
>> the Standard associated with a Header, this should constitute about 10
>> minutes of work.
>>
>
> Then it shouldn't take you much more than 20 minutes to do it. That has
> the great advantage that it shows your commitment -- tt's easy to
> suggest that other people should do work for you. But then you'll also
> be on the hook for maintaining what you've written as the standard
> changes. Writing the same thing more than once is expensive.
>
Actually it is not quite that simple of an exercise.  Copying from PDF is
not as easy as copying from regular text.
http://bugs.kde.org/show_bug.cgi?id=108144

How shall I provide the text files?
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:

[...]
>>
> Actually it is not quite that simple of an exercise.  Copying from PDF is
> not as easy as copying from regular text.
> http://bugs.kde.org/show_bug.cgi?id=108144
>
> How shall I provide the text files?

For the sake of clarity, the question is not 'how shall I prepare the text
files?'  That is mostly complete.  The question is 'where shall I send
them?'
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

I find the Standard document difficult to use as a reference.  I understa=
nd
that is not the primary goal of the document, but I see no reason that it
could not serve that purpose better than it does.  In general, I find C++
documentation excessively difficult to use as a quick reference.  This go=
es
beyond the fact that C++ is a very complex language. =20

For one example, let me explain what promted me to write this post.  I wa=
nt
to be able to view the entire Standard Library declaration in terms of
headers and their contents.  Though the standard headers need not be actu=
al
files, they /can/ be.  I would like to be able to view them as just that.=
=20
Or as text documents organized as they would be on a file system.  I've
actually copied several of the declarations from the Standard to files.=20
This is not a straightforward exercise.  For example =A727.6.1 =B61 state=
s "The
header <istream> defines two types and a function signature that control
input from a stream buffer."

As I scroll through the text to find where these are declared, I encounte=
r
in =A727.6.1.1 what appears to be one of the type definitions along with =
some
associated extraction operators.  Fine.  I copy those into a file called
istream.hh.  Scroll down to =A727.6.1.2.2, hmmm,  basic_istream::sentry, =
that
probably goes in there as well.  Scroll some more, and I see =A727.6.1.2.=
2
Arithmetic Extractors.  Let me ponder this for a moment,  are these shown
as part of a complete declaration with the namespace included?  No.  Then
they probably don't belong in the header as such.  Are they discussin
what's already been declared in what I have copied?  Scroll back up, or
look at what I copied.  They look to have the same signature as the items
listed as "Formatted input", but the parameter names are not the same.=20
Looking more closely, I notice that the content of what I have pasted
indicates these will be discussed in =A727.6.1.2.  OK, I'll assume that's
what they are. =20

Scrolling down somemore, I see =A727.6.1.4 Standard basic_istream
manipulators.  I haven't seen anything to indicate a different header is
under discussion.  It looks as if the following four lines of code should
also go into my istream.hh, but I'm really not sure.

Further down I encounter =A727.6.1.5 Class template basic_iostream.  Does=
 this
also go in my istream.hh?  Well, I recall reading in Josuttis's TC++SL th=
at
<istream> contains both the definition for classes that support input onl=
y,
and those that support input and output.  This is not indicated by the
first sentence in =A727.6 which talks about two types and a function.

I do not believe there is a good reason for the Standard document to be t=
his
difficult to view from the level that I am describing.  In =A717.1.1 of
TC++PL(SE) we are told "This section list the common and almost common
members of the standard containers.  For more details, read your standard
headers(<vector>, <list>, <map>, etc.; =A716.1.2)"  That statement might =
be
taken differently than I understood it, but my understanding was (and sti=
ll
is) that I should look at the header(files) on my file system.  I have a
few different versions of the C++ Standard Library.  Borland, Microsoft,
STLPort and GCC.  None of these offer the standard headers in a way that
facilitates determining what they actually contain.

It seems reasonable to me that the Standard Committee would make the
standard header declarations available in the form that they are presente=
d
in the Standard, but as separate files holding nothing but the header
declarations, and references back to the relevant text in the Standard.
See, for example, the W3C Document Object Model standard language binding=
:

http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/java-binding.html


--=20
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Steven T. Hatton wrote:

>
> It seems reasonable to me that the Standard Committee would make the
> standard header declarations available in the form that they are presented
> in the Standard, but as separate files holding nothing but the header
> declarations, and references back to the relevant text in the Standard.
>

Volunteering other people to do this work won't get it done. Write it up
and propose it.

--

Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

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

[..]
> I do not believe there is a good reason for the Standard document to
> be this
> difficult to view from the level that I am describing.  In    17.1.1 of
> TC++PL(SE) we are told "This section list the common and almost common
> members of the standard containers.  For more details, read your
> standard
> headers(<vector>, <list>, <map>, etc.;    16.1.2)"  That statement might
> be
> taken differently than I understood it, but my understanding was (and
> still
> is) that I should look at the header(files) on my file system.  I have
> a
> few different versions of the C++ Standard Library.  Borland,
> Microsoft,
> STLPort and GCC.  None of these offer the standard headers in a way
> that
> facilitates determining what they actually contain.

That's because the standard headers contain circularites, that are
usually resolved by dividing the files into smaller parts, and including
these parts in the required headers.

One example is that <string> contains references to <stdexcept> whose
classes have string parameters. They would both have to include each
other!

The standard document describes what you get when you include a specific
header, not what each header file literally contains. This is also
exactly what you have noticed.


> It seems reasonable to me that the Standard Committee would make the
> standard header declarations available in the form that they are
> presented
> in the Standard, but as separate files holding nothing but the header
> declarations, and references back to the relevant text in the
> Standard.

But they wouldn't be useful in that form, because they wouldn't compile
anyway.


Bo Persson


---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Pete Becker wrote:
> Steven T. Hatton wrote:
>
>>
>> It seems reasonable to me that the Standard Committee would make the
>> standard header declarations available in the form that they are
>> presented
>> in the Standard, but as separate files holding nothing but the header
>> declarations, and references back to the relevant text in the Standard.
>>
>
> Volunteering other people to do this work won't get it done. Write it up
> and propose it.
>

Actually, that was a little more encouraging than I meant it to be. That
would be difficult to maintain, and as project editor I'd rather not be
responsible for doing it. There's lots of third-party documentation that
gives the complete header contents.

--

Pete Becker
Dinkumware, Ltd. (http://www.dinkumware.com)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Pete Becker wrote:

> Steven T. Hatton wrote:
>
>>
>> It seems reasonable to me that the Standard Committee would make the
>> standard header declarations available in the form that they are
>> presented in the Standard, but as separate files holding nothing but the
>> header declarations, and references back to the relevant text in the
>> Standard.
>>
>
> Volunteering other people to do this work won't get it done. Write it up
> and propose it.

As far as who actually does the work, I would expect the people working on a
particular part of the Standard would be most qualified to provide the file
for their particular header.  To a person familiar with given section of
the Standard associated with a Header, this should constitute about 10
minutes of work.

I'm fishing around to see if there's interest in providing the Standard
Headers in the form of source files.  Or more to the point, if there is
resistance to it.

In the past I've been told that the things I object to in the wording and
structure of the C++ Standard are simply the nature of a formal language
specifications.  I could accept that if it weren't for the fact that I've
seen other language specifications.  I'm really concerned with more than
simply whether the Standard Headers are available in source code form.  I'm
trying to persuade people the take a different approach ('attitude' may be
a better word than 'approach') to how the language and library are
presented.

The idea crossed my mind that it might also be useful to put much of the
text of the standard in C++ comment blocks, perhaps with Doxygen markup.
This, of course, would require more work, and more politics. Often I like
to see just the code, sans comments. Part of the reason I'd like to have
the Standard Header files available in hard copy, and in the form of
almost[*] proper C++ is that I find formatting things like this:

template<class FwdIt1, class FwdIt2, class Pr>
    FwdIt1 search(FwdIt1 first1, FwdIt1 last1,
        FwdIt2 first2, FwdIt2 last2, Pr pred);

all on one line can often be easier for me to read.  I suspect others won't
agree. Having my own copy means I can play with the formatting to suit my
taste.  I can also point various tools at these to generate different
abstract views of the code structure and file dependencies.

I believe viewing the Standard Library from this perspective will reveal its
structure (and lack thereof).  It may even be instructive to concatenate
all of the Standard Headers into one file in order to view the entire
namespace std{} as a whole.

For an example of a language standard document that was clearly written with
pedagogical intent see this - of particular interest in this context is
Appendix D[**]:
http://www.ecma-international.org/publications/files/ecma-st/ECMA-334.pdf

If you wish, you can fetch mono and monodoc from here, and see the
organizational approach used to present the language and libraries:
http://www.mono-project.com/Main_Page

I cannot comment on the actual C# library specification document because I
have not seen it.

A language standard designed to be virtually incomprehensible can be found
here:
http://www.ecma-international.org/publications/standards/Ecma-262.htm
But there is a decent reference guide:
http://research.nihonsoft.org/javascript/CoreReferenceJS15/index.html

As for a language with a reasonably well organized and comprehensive library
take a look here:
http://java.sun.com/j2se/1.5.0/docs/api/

The language standard document itself is, IMO, more comprehensible than the
C++ Standard.
http://java.sun.com/docs/books/jls/third_edition/html/j3TOC.html

To be clear, I am not saying C++ should be just like C#, or just like Java.
I'm not even suggesting C++ should change significantly to be more like
either of these languages.  I really believe C++ libraries could be created
that provide all the functionality of these languages using the current
C++.  I do, however, believe there are things to be learned from these
other languages.  In this context I am mostly referring to how they are
documented.  That, however, is somewhat dependent on how they are
organized, and designed.

[*] There are a few `typedef implementation defined type;' statements which
will clearly make the headers less than proper C++ without providing
definitions.

[**] Just so there's no misconception that I was motivated by the C#
standard, have it be known that I discovered Appendix D while composing
this message.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Bo Persson wrote:
=20
I've already decided this is probably not going to fly, so the subsequent
discussion in somewhat academic.

> That's because the standard headers contain circularites, that are
> usually resolved by dividing the files into smaller parts, and includin=
g
> these parts in the required headers.
>=20
> One example is that <string> contains references to <stdexcept> whose
> classes have string parameters. They would both have to include each
> other!

No matter how you break it up, you are going to end up doing something to
break the cycle.  I suspect that could be done without braking the files
up.  You may need a little dab of gluecode, but I would very much like to
see an argument for much more than that.  If you are #including one file =
in
another, then you have not broken them up.  File scope is defined by
translation units, not filesystem files.
=20
> The standard document describes what you get when you include a specifi=
c
> header, not what each header file literally contains. This is also
> exactly what you have noticed.

The textbook I used to learn C++ said that interfaces should be
selfdescribing.  The Standard Headers are the interface between the
programmer and the Standard Library implementation.  As such, they should
be selfdescribing.

http://www.research.att.com/~bs/3rd.html
See: =A78.2.4 and =A724.4.2

Also of interest in this context is =A79.2.2 of=20
http://www.josuttis.com/libbook/index.html
In particular the final paragraph on page 324.  Which I just read for the
first time today.

>> It seems reasonable to me that the Standard Committee would make the
>> standard header declarations available in the form that they are
>> presented
>> in the Standard, but as separate files holding nothing but the header
>> declarations, and references back to the relevant text in the
>> Standard.
>=20
> But they wouldn't be useful in that form, because they wouldn't compile
> anyway.

I have to disagree.  First of all, I do have several of the Headers copie=
d
to my harddrive, and I find them useful.  Furthermore, they need not
compile in order to be parsed. I can open the files in Emacs and see them
with the same syntax highlighting that my mind is conditioned to
immediately understand.  I can view them with speedbar to see a compact
representation of their structure, and I can use other tools to process
them for purposes of creating UML diagrams, dependency graphs, code
completion databases, etc.

--=20
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]