stl docs

[Andrew Sutton]

All,

I took some time off from writing graph docs to umm... generate lots  
of stubs for STL docs. I have committed a bunch of blank quickbook  
files into boost_docs/runk/lib/standard in case somebody wants to  
occasionally jot down notes on a particular concept. Right now, all  
we have are stubbed-out concepts. I haven't finished adding all of  
the reference material yet.

If you contribute, I would prefer not to copy directly from the SGI  
stie since that would be a little plagiaristic. Also, that would make  
this a copy of their work and subject to their copyright restrictions  
- which I'd like to avoid. So, It's okay to paraphrase but be sure to  
make it your own. It may be harder to do this with concept documents  
than reference docs.

I'll be adding to this from time to time. If you want to see the most  
update-to-date version, it's here:

http://tinyurl.com/35bxkj

If anybody wants to help out, there's certainly lots of room for  
parallel development. Lots and lots of docs.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/19/07, Andrew Sutton <asutton@...> wrote:
> All,
>
> I took some time off from writing graph docs to umm... generate lots
> of stubs for STL docs. I have committed a bunch of blank quickbook
> files into boost_docs/runk/lib/standard in case somebody wants to
> occasionally jot down notes on a particular concept. Right now, all
> we have are stubbed-out concepts. I haven't finished adding all of
> the reference material yet.

Wow! Great Andrew... this can really fuel the standard docs project.

> If you contribute, I would prefer not to copy directly from the SGI
> stie since that would be a little plagiaristic. Also, that would make
> this a copy of their work and subject to their copyright restrictions
> - which I'd like to avoid. So, It's okay to paraphrase but be sure to
> make it your own. It may be harder to do this with concept documents
> than reference docs.

I think that this is a very wise advice.

We have been informally discussing the fate of the Standard C++
Library Boosted Documentation in our community blog.

Jake and Stjepan have made some very important points.
One in particular was a revelation for me:

   Stjepan said...

     "I could see why maintaining standard C++ library documentation
     as proposed would benefit Boost greatly. It would likely
     become the (or one of the) standard library documentation sites,
     and would immediately raise awareness of Boost to just about any
     C++ programmer out there."

The complete thread is here:
http://tinyurl.com/3cjhpe

We should move further discussion here.

Best regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Andrew Sutton]

> Wow! Great Andrew... this can really fuel the standard docs project.

Yes... There was much rapid typing, and opening of files. Now, my  
wrists hurt, but never before have so many empty files been committed  
to such a great cause :)

> We have been informally discussing the fate of the Standard C++
> Library Boosted Documentation in our community blog.
>
> Jake and Stjepan have made some very important points.
> One in particular was a revelation for me:

I read those this morning...

> We should move further discussion here.

We could, but I actually prefer the mailing list since this  
discussion is fairly on-topic.  I'm going to pick on something Jake  
(Voytko) said:

        "I think we may want to split the documentation for each header into  
two discrete segments: reference, and best practices"

This is mostly in the right direction, except that there's a little  
more to it. Many libraries require or provide concept documentation.  
Concise, well-organized, and well-presented concepts are going to be  
critical for C++ developers - more so in the future than now, perhaps.

I would also like to make a distinction between "reference documents"  
and "code-listings". There are a number of libraries that sell their  
API reference material as a simple listing of header files, classes,  
and functions (a la Doxygen). This is a lazy way to write docs and  
isn't any better than looking at the header file. Reference documents  
should have a complete (textual) description of the the function's  
behaviors, its parameters, its preconditions and postconditions (if  
relevant), return values, and exceptions.

And then there's the examples... Each reference doc should contain a  
meaningful example that illustrates best-practice use of the API. And  
what I mean by "meaningul" is that examples should draw from a real  
problem as much as possible. Here's the SGI example of std::vector:

vector<int> V;
V.insert(V.begin(), 3);
assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3);

This is one of the most egregious examples I've ever read. There are  
roughly 25 methods in this class and the example shows 5 - and none  
of them are very useful. Giving meaningful real-world examples helps  
the reader connect with the material since it's showing the  
usefulness of the subject in a relevant way. A good example of using  
a vector might be the creation of a histogram (counting observations)  
since it would rely on the random access properties provided by the  
vector.

Examples of _bad practice_ could follow the "good example". These  
might illustrate things like iterator invalidation. We could also  
have "snippets" that show the best way to perform common tasks (like  
erasing a range of elements).

MSDN actually does a pretty good job with reference docs. That should  
probably serve as the model.

I'll re-post this as a comment on the blog-site just in case.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/20/07, Andrew Sutton <asutton@...> wrote:
> > We should move further discussion here.
>
> We could, but I actually prefer the mailing list since this
> discussion is fairly on-topic.

This is what I mean. We should move the discussion to the
list and out of the blog. Sorry if I was not clear.

Best regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/20/07, Andrew Sutton <asutton@...> wrote:

> I'm going to pick on something Jake
> (Voytko) said:
>
>         "I think we may want to split the documentation for each header into
> two discrete segments: reference, and best practices"
>
> This is mostly in the right direction, except that there's a little
> more to it. Many libraries require or provide concept documentation.
> Concise, well-organized, and well-presented concepts are going to be
> critical for C++ developers - more so in the future than now, perhaps.

Agree.

> I would also like to make a distinction between "reference documents"
> and "code-listings". There are a number of libraries that sell their
> API reference material as a simple listing of header files, classes,
> and functions (a la Doxygen). This is a lazy way to write docs and
> isn't any better than looking at the header file. Reference documents
> should have a complete (textual) description of the the function's
> behaviors, its parameters, its preconditions and postconditions (if
> relevant), return values, and exceptions.

100% agree :)
Doxygen docs are good in Java where there is only OO. In C++, I like to
see thing like Boost.MultiIndex reference section.

> And then there's the examples... Each reference doc should contain a
> meaningful example that illustrates best-practice use of the API. And
> what I mean by "meaningul" is that examples should draw from a real
> problem as much as possible. Here's the SGI example of std::vector:
>
> vector<int> V;
> V.insert(V.begin(), 3);
> assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3);

> This is one of the most egregious examples I've ever read. There are
> roughly 25 methods in this class and the example shows 5 - and none
> of them are very useful.

:P

> Giving meaningful real-world examples helps
> the reader connect with the material since it's showing the
> usefulness of the subject in a relevant way. A good example of using
> a vector might be the creation of a histogram (counting observations)
> since it would rely on the random access properties provided by the
> vector.

Independent of having a central place for std + boost concepts with
dynamic navigation tools to aid the user, I vot to treat each standard
C++ sublibrary as if we were documenting a boost library.
I would like to see a "std::vector docs" with a one minute tutorial, a
tutorial, an examples section, a reference, performance, etc.

It is a lot of work... but we can take your approach here too. We can
add stubs and let people collaborate. We can maintain two version,
one public in the sandbox where anyone can add stuff. And a
moderated version inside boost that takes the best things of the
sandbox version.

Best regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Andrew Sutton]

> 100% agree :)
> Doxygen docs are good in Java where there is only OO. In C++, I  
> like to
> see thing like Boost.MultiIndex reference section.

To be honest, I find Javadoc'd documentation entirely unreadable and  
pretty far from helpful.

> Independent of having a central place for std + boost concepts with
> dynamic navigation tools to aid the user, I vot to treat each standard
> C++ sublibrary as if we were documenting a boost library.
> I would like to see a "std::vector docs" with a one minute tutorial, a
> tutorial, an examples section, a reference, performance, etc.

Tutorial-ish stuff is necessary and I agree that it would be great to  
have little five-minute tutorials, but they need to be separate from  
the reference docs. Reference material needs to be both concise and  
precise. Tutorials, introductions, and/or articles have a lot more  
freedom for wordiness and getting off-topic. For example, the  
std::list<> tutorial could have a great aside on "Why list.size() is  
theta(n)".

I think tutorial sections should come first, with reference material  
in the back.

> It is a lot of work... but we can take your approach here too. We can
> add stubs and let people collaborate. We can maintain two version,
> one public in the sandbox where anyone can add stuff. And a
> moderated version inside boost that takes the best things of the
> sandbox version.

I think that's a pretty good idea. I was thinking something similar.

Andrew Sutton
asutton@...



-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Paul A. Bristow-2]

 

>-----Original Message-----
>From: boost-docs-bounces@...
>[mailto:boost-docs-bounces@...] On Behalf Of
>Andrew Sutton
>Sent: 20 July 2007 13:18
>To: Boost documentation format, structure, and processing discussion
>Subject: Re: [Boost-docs] stl docs

>And then there's the examples... Each reference doc should contain a  
>meaningful example that illustrates best-practice use of the API. And  
>what I mean by "meaningul" is that examples should draw from a real  
>problem as much as possible. Here's the SGI example of std::vector:
>
>vector<int> V;
>V.insert(V.begin(), 3);
>assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3);
>
>This is one of the most egregious examples I've ever read. There are  
>roughly 25 methods in this class and the example shows 5 - and none  
>of them are very useful. Giving meaningful real-world examples helps  
>the reader connect with the material since it's showing the  
>usefulness of the subject in a relevant way. A good example of using  
>a vector might be the creation of a histogram (counting observations)  
>since it would rely on the random access properties provided by the  
>vector.
>
>Examples of _bad practice_ could follow the "good example". These  
>might illustrate things like iterator invalidation. We could also  
>have "snippets" that show the best way to perform common tasks (like  
>erasing a range of elements).
>
>MSDN actually does a pretty good job with reference docs. That should  
>probably serve as the model.

But I find the MSDN examples are often not Standard C++ and not Boost style,
and they are also often a bit thin, and very thinly commented.

Personally, I'd like something more in this style, deliberately over-commented to restate what to some seem obvious.  Perhaps...

vector<int> V; // Constructs an empty vector.
assert(V.size() == 0); // Should be zero size,
assert(V.empty == true); // and should be empty too.
V.insert(V.begin(), 3); // Increases size by 1, and inserts the value 3 at the front.
assert(V.size() == 1);  // Check size is increased by 1, and is 1.
assert(V.capacity() >= 1); // Capacity could be more than size if reserved (or released).
assert(V.capacity() >= V.size()) // Or something is horribly wrong!
&& V[0] == 3); // Check value is same as just inserted.
...

Provided we have colored coding so that comments are green (or whatever bad-taste color you prefer ;-), localising the comments in
the code makes it easier to read.  And ALL are compiled together.

> .. but we can take your approach here too. We can
> add stubs and let people collaborate. We can maintain two version,
> one public in the sandbox where anyone can add stuff. And a
> moderated version inside boost that takes the best things of the
> sandbox version.

> I think that's a pretty good idea. I was thinking something similar.

I think that's a REALLY good idea.

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow@...

 





-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Andrew Sutton]

>>
>> MSDN actually does a pretty good job with reference docs. That should
>> probably serve as the model.
>
> But I find the MSDN examples are often not Standard C++ and not  
> Boost style,
> and they are also often a bit thin, and very thinly commented.

I don't think I was being very precise about what the "model" was. It  
certainly isn't the code in their documents - some of that is pretty  
hairy and obviously targets their own infrastructure and compilers. I  
just meant the depth of documentation. I've found that much of it is  
actually fairly good. However, some of the examples can make your  
eyes bleed.

> Personally, I'd like something more in this style, deliberately  
> over-commented to restate what to some seem obvious.  Perhaps...
>
> vector<int> V; // Constructs an empty vector.
> assert(V.size() == 0); // Should be zero size,
> assert(V.empty == true); // and should be empty too.
> V.insert(V.begin(), 3); // Increases size by 1, and inserts the  
> value 3 at the front.
> assert(V.size() == 1);  // Check size is increased by 1, and is 1.
> assert(V.capacity() >= 1); // Capacity could be more than size if  
> reserved (or released).
> assert(V.capacity() >= V.size()) // Or something is horribly wrong!
> && V[0] == 3); // Check value is same as just inserted.
> ...
>
> Provided we have colored coding so that comments are green (or  
> whatever bad-taste color you prefer ;-), localising the comments in
> the code makes it easier to read.  And ALL are compiled together.

Although I'm a big fan of well-commented code, I'm not sure that the  
do-something-and-assert-that-it-worked style of examples effectively  
conveys effective usage of class or function. That's really showing  
the pre- and post-conditions, which should be made explicit but  
probably not as an example.

Andrew Sutton
asutton@...



-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Scott McMurray-2]

On 20/07/07, Andrew Sutton <asutton@...> wrote:
> > 100% agree :)
> > Doxygen docs are good in Java where there is only OO. In C++, I
> > like to
> > see thing like Boost.MultiIndex reference section.
>
> To be honest, I find Javadoc'd documentation entirely unreadable and
> pretty far from helpful.

I can never tell what's important in a Javadoc, and they often seem to
go on forever.  Of course, that's assuming I can actually find what
I'm looking for, which is rather rare unless I already know what it
is.

> > Independent of having a central place for std + boost concepts with
> > dynamic navigation tools to aid the user, I vot to treat each standard
> > C++ sublibrary as if we were documenting a boost library.
> > I would like to see a "std::vector docs" with a one minute tutorial, a
> > tutorial, an examples section, a reference, performance, etc.
>
> Tutorial-ish stuff is necessary and I agree that it would be great to
> have little five-minute tutorials, but they need to be separate from
> the reference docs. Reference material needs to be both concise and
> precise. Tutorials, introductions, and/or articles have a lot more
> freedom for wordiness and getting off-topic. For example, the
> std::list<> tutorial could have a great aside on "Why list.size() is
> theta(n)".

Having an "Official" Boost reference document for the standard library
would be great.  Assuming it'd be in quickbook or similar, it might
even be turnable into a treeware version.

It's nowhere near everything that's needed, but I can offer under some
appropriate license some articles I've been writing that might make an
acceptable starting point:
http://gpwiki.org/index.php/C_plus_plus:Modern_C_plus_plus

~ Scott McMurray

P.S. Isn't list's size only O(n), since some implementations make it theta(1)?

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Andrew Sutton]

> Having an "Official" Boost reference document for the standard library
> would be great.  Assuming it'd be in quickbook or similar, it might
> even be turnable into a treeware version.
>
> It's nowhere near everything that's needed, but I can offer under some
> appropriate license some articles I've been writing that might make an
> acceptable starting point:
> http://gpwiki.org/index.php/C_plus_plus:Modern_C_plus_plus

This is more tutorial-style documentation - which isn't really my  
priority at the moment. Also - this will sound condescending - I am  
continually unimpressed by the software quality in the gaming  
industry so I'm a little reluctant to borrow examples from the  
domain. Not to say that there isn't some good stuff (or good people)  
out there, but I don't see many shining examples coming from the domain.

> P.S. Isn't list's size only O(n), since some implementations make  
> it theta(1)?

I'm not sure if there are any implementations that implement it in  
theta(1) - somebody would have to check individual implementations.  
My gut feeling is that list.size() is generally theta(n) everywhere  
so that list.splice() can be theta(1). I could very well be wrong.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Jake Voytko]

On 7/20/07, Andrew Sutton <asutton@...> wrote:

> Having an "Official" Boost reference document for the standard library
> would be great.  Assuming it'd be in quickbook or similar, it might
> even be turnable into a treeware version.
>
> It's nowhere near everything that's needed, but I can offer under some
> appropriate license some articles I've been writing that might make an
> acceptable starting point:
> http://gpwiki.org/index.php/C_plus_plus:Modern_C_plus_plus

This is more tutorial-style documentation - which isn't really my
priority at the moment. Also - this will sound condescending - I am
continually unimpressed by the software quality in the gaming
industry so I'm a little reluctant to borrow examples from the
domain. Not to say that there isn't some good stuff (or good people)
out there, but I don't see many shining examples coming from the domain.

> P.S. Isn't list's size only O(n), since some implementations make
> it theta(1)?

I'm not sure if there are any implementations that implement it in
theta(1) - somebody would have to check individual implementations.
My gut feeling is that list.size() is generally theta(n) everywhere
so that list.splice() can be theta(1). I could very well be wrong.

According to sgi.com, the STL has complexity guarantees in the specification
<http://www.sgi.com/tech/stl/complexity.html>

So I think we should use these.

Jake

P.S. Sorry, Matias, for not continuing the discussion on the blog, but I didn't want to have two branches of the same conversation. We can post a summary of the decisions reached later.

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Matias Capeletto]

On 7/20/07, Jake Voytko <jakevoytko@...> wrote:

> P.S. Sorry, Matias, for not continuing the discussion on the blog, but I
> didn't want to have two branches of the same conversation. We can post a
> summary of the decisions reached later.

The blog is about informal and behind the scene information, about how
we _feel_ about some of IBD subjects. The present discussion belongs
to the boost-docs list.
We do not need to add any summary to the blog. It is not the idea.

King regards
Matias

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[David Abrahams]

on Fri Jul 20 2007, "Jake Voytko" <jakevoytko-AT-gmail.com> wrote:

> According to sgi.com, the STL has complexity guarantees in the specification
> <http://www.sgi.com/tech/stl/complexity.html>
>
> So I think we should use these.

Please use the C++ standard instead.  It is the only authoritative
source, and the SGI docs are not always consistent with it.

--
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com


-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Andrew Sutton]

> According to sgi.com, the STL has complexity guarantees in the  
> specification
> <http://www.sgi.com/tech/stl/complexity.html>
>
> So I think we should use these.

Yup... but in general complexity is guaranteed by the /concept/ not  
the class. For example the Container concept requires C.size() to be  
in O(n) where n is the number of elements in C. There's a not at the  
bottom that says this is satisfied by vector and deque who have C.size
() in O(1). Of course,  O(1) is in O(n) so its okay.

I think in general, giving bounds on algorithms and data structure  
operations is a "Good Thing" and we should definitely continue to do  
so (at least where relevant). Documenting the complexity of the  
iterator_category() function is probably overkill. Actually, not  
doing so would not be best practice.

Andrew Sutton
asutton@...

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Paul A. Bristow-2]

>-----Original Message-----
>From: boost-docs-bounces@...
>[mailto:boost-docs-bounces@...] On Behalf Of
>Andrew Sutton
>Sent: 20 July 2007 15:39
>To: Boost documentation format, structure, and processing discussion
>Subject: Re: [Boost-docs] stl docs
>
>> Having an "Official" Boost reference document for the
>standard library
>> would be great.  Assuming it'd be in quickbook or similar, it might
>> even be turnable into a treeware version.
>>
>> It's nowhere near everything that's needed, but I can offer
>under some
>> appropriate license some articles I've been writing that
>might make an
>> acceptable starting point:
>> http://gpwiki.org/index.php/C_plus_plus:Modern_C_plus_plus
>
>This is more tutorial-style documentation - which isn't really my  
>priority at the moment.

But I'm impressed by the *style* of, say, vector *examples*:

http://gpwiki.org/index.php/C_plus_plus:Modern_C_plus_plus:Vectors

(Except that, in nit-pick mode, I can't understand why comments don't start their sentences with Capital Letter, and end with a
period?)

This is the sort of example that I believe would be most helpful, and I hope can be referenced directly from Quickbook.

Doxygen seems fine for reference, but I've not seen it produce *nice* annotated examples.  Perhaps that's my ignorance though?

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
[phone] & SMS, Mobile [phone] & SMS
pbristow@...

 






-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Andrew Sutton]

>> So I think we should use these.
>
> Please use the C++ standard instead.  It is the only authoritative
> source, and the SGI docs are not always consistent with it.

Good point. Out of which version of the standard should we be  
referencing? I have a copy of the 1998 first edition floating around  
on my laptop, but I can't seem to tell if that's the most recent  
published version. I'd hate to be writing docs for something a couple  
years out of date.

Andrew Sutton
asutton@...


-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Jake Voytko]

On 7/20/07, Andrew Sutton <asutton@...> wrote:

>> So I think we should use these.
>
> Please use the C++ standard instead.  It is the only authoritative
> source, and the SGI docs are not always consistent with it.

Good point. Out of which version of the standard should we be
referencing? I have a copy of the 1998 first edition floating around
on my laptop, but I can't seem to tell if that's the most recent
published version. I'd hate to be writing docs for something a couple
years out of date.

Andrew Sutton
asutton@...

If that is the most recent version, could you post that to the Vault, or an otherwise accessible location? I feel that that could come in handy for this project :)

Jake

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[John Maddock]

Jake Voytko wrote:
>> If that is the most recent version, could you post that to the
>> Vault, or an
>> otherwise accessible location? I feel that that could come in handy
>> for this
>> project :)

The most recent version is the C++ 2003 std, that includes the first TC.
It's paper n1316 on the C++ std website, but appears not to be publicly
available :-(

The draft for the next std is here:
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2315.pdf, but we
probably shouldn't be using that.

John.


-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Jake Voytko]

It appears that it costs about 300 dollars to purchase the standard from ISO.org. Ouch.

It also appears that it may or may not be available as a PDF in the top 5 results if you search for the standard name, 14882-2003.

Jake

On 7/20/07, John Maddock <john@...> wrote:

Jake Voytko wrote:
>> If that is the most recent version, could you post that to the
>> Vault, or an
>> otherwise accessible location? I feel that that could come in handy
>> for this
>> project :)

The most recent version is the C++ 2003 std, that includes the first TC.
It's paper n1316 on the C++ std website, but appears not to be publicly
available :-(

The draft for the next std is here:
http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2315.pdf, but we
probably shouldn't be using that.

John.


-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs

[Stjepan Rajko-3]

On 7/20/07, Jake Voytko <jakevoytko@...> wrote:
> It appears that it costs about 300 dollars to purchase the standard from
> ISO.org. Ouch.
>
> It also appears that it may or may not be available as a PDF in the top 5
> results if you search for the standard name, 14882-2003.
>

LOL - nice!!! Thanks for what may or may not be a great tip :-)

Stjepan

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Boost-docs mailing list
Boost-docs@...
Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs