On Thu, Jun 30, 2011 at 6:08 PM, Stephan Beal <[email protected]> wrote: > On Thu, Jun 30, 2011 at 5:58 PM, bradley.meck <[email protected]> > wrote: >> >> http://v8.googlecode.com/svn/trunk/include/v8.h ctrl+f 'AS(' > > stephan@tiny:~/src/google/v8/src$ svn info > ... > Last Changed Date: 2011-06-23 12:27:56 +0200 (Thu, 23 Jun 2011) > stephan@tiny:~/src/google/v8/src$ grep -i -w as v8.h > // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT > that's from the trunk, though it is a few days out of date. > >> >> Not sure why you aren't finding stuff, but its up there (and reading the >> template should be enough for that to not need more doc). > > i'm really not going to defend the need for _docs_ for clients. >> >> A.) the competitions docs (lua and python are on par I think, but have >> them in nice HTML formats). > > i don't use those, so that doesn't bother me. > >> >> B.) V8.h, not sure where yours is coming from > > v8.h - the public headers which are included by client code like mine. > >> >> C.) Examples, always a good way to grok what something is doing > > i saw examples of As() and had never seen it before. i looked (first thing) > in the the API docs but they were empty, which was why i asked. The examples > don't explain the documented semantics which clients can depend on they. > They show us how one developer tried to use it. Any behaviour which is not > document is undefined, and clients cannot depend on it.
I don't think we need to debate that the documentation of v8.h is not the best. Many things are not fully specified, some aren't at all. In such a case, yes, the best one can do is read the code. Especially in a header. In the v8 namespace as the embedding api is isolated reasonably well from the details of the implementation. Documentation may be a good indication that the authors intend to uphold the semantics of the api and vice versa, but I have yet to see examples where v8 changed behavior willy-nilly. Handle::As has been in there through at least v2.2, maybe you have an old branch checked out. Matthias > -- > ----- stephan beal > http://wanderinghorse.net/home/stephan/ > > -- > v8-users mailing list > [email protected] > http://groups.google.com/group/v8-users -- v8-users mailing list [email protected] http://groups.google.com/group/v8-users
