JSAPI User Guide out of date

classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

JSAPI User Guide out of date

greg
I'm trying to build the hello world example in the JSAPI User Guide: https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/JSAPI_User_Guide

It appears to be out of date. This line for instance:
JSRuntime *rt = JS_NewRuntime(8L * 1024L * 1024L);

doesn't build (wrong number of arguments). Is there an up-to-date version of the user guide?

Thanks.
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

greg
Actually, it looks like the version of mozjs I've downloaded is older. I thought the current standalone version is 31 but the docs for this function https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/JSAPI_reference/JS_NewRuntime show the version of JS_NewRuntime in it is deprecated as of version 32.

I guess my question should be, is there a User Guide for the current standalone version?
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

greg
In reply to this post by greg
I can't help but wonder if I'm coming into this in the middle of some kind of change?

https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey/JSAPI_reference/JS_SetErrorReporter

The documentation here shows JSRuntime *rt as a parameter and the hello world I'm following uses it that way but the compiler says a JSContext * is what is required and, if you look at the documentation, you'll see that listed as a parameter where JSRuntime should be. It looks like the documentation is in mid-change.
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

greg
In reply to this post by greg
This documentation is pretty much unusable. It's FOSS so I'm not going to complain (ok I guess I am complaining) but I have to say no documentation would be as good as what is there. Every time I start to add a new piece from the users guide I discover that the function being used has been deprecated since 1.8 and nothing seems compatible.

How are people actually learning to use this API?
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Kannan Vijayan
Hi greg,

You are right, the documentation is indeed a bit out of date.  The
engine has gone through a series of pretty rapid changes recently and
the API documentation hasn't kept up.  To solve your immediate problem,
I'd advise taking a look at js/src/shell.cpp for whatever SpiderMonkey
distribution you are trying to embed:

https://dxr.mozilla.org/mozilla-central/source/js/src/shell/js.cpp

It implements a functional shell and is a good place to crib API usage from.

That said, I agree that this should be resolved.  I spoke with the
module maintainer, and he seems to agree that deleting the docs at this
point would be better than leaving them there.  Then we could maybe
slowly build up new API docs in some way that guaranteed that they
tracked the actual shipping API.  One way to do this might be to
generate the docs from special "apidocs" c++ files, where the generator
ensures that the source compiles before the docs are extracted from the
source.

Kannan

On 2015-03-07 2:55 PM, [hidden email] wrote:
> This documentation is pretty much unusable. It's FOSS so I'm not going to complain (ok I guess I am complaining) but I have to say no documentation would be as good as what is there. Every time I start to add a new piece from the users guide I discover that the function being used has been deprecated since 1.8 and nothing seems compatible.
>
> How are people actually learning to use this API?
> _______________________________________________
> dev-tech-js-engine mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-tech-js-engine

_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

greg
In reply to this post by greg
On Saturday, 7 March 2015 13:52:36 UTC-8, Kannan Vijayan  wrote:

> Hi greg,
>
> You are right, the documentation is indeed a bit out of date.  The
> engine has gone through a series of pretty rapid changes recently and
> the API documentation hasn't kept up.  To solve your immediate problem,
> I'd advise taking a look at js/src/shell.cpp for whatever SpiderMonkey
> distribution you are trying to embed:
>
> https://dxr.mozilla.org/mozilla-central/source/js/src/shell/js.cpp
>
> It implements a functional shell and is a good place to crib API usage from.
>
> That said, I agree that this should be resolved.  I spoke with the
> module maintainer, and he seems to agree that deleting the docs at this
> point would be better than leaving them there.  Then we could maybe
> slowly build up new API docs in some way that guaranteed that they
> tracked the actual shipping API.  One way to do this might be to
> generate the docs from special "apidocs" c++ files, where the generator
> ensures that the source compiles before the docs are extracted from the
> source.
>

Thanks Kannan. The shell looks like a good place to start.
-Greg.
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Eric Shepherd

I'd love to have a real discussion about how to get properly up to date documentation for JSAPI. Out of date content makes me sad, as a member of the docs team and someone who craves completeness in all things.





The first thing to get into is a real evaluation of whether or not nuking the existing content from orbit is actually the best way to begin.





If it is, I would still recommend archival instead of deletion, so any still-useful tidbits can be copied and pasted.





But that is still a drastic choose of action, so I'd love to learn more.





Eric Shepherd


Sr. Technical Writer


developer.mozilla.org

_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

greg
In reply to this post by greg
On Sunday, 8 March 2015 16:23:31 UTC-7, Eric Shepherd  wrote:
> I'd love to have a real discussion about how to get properly up to date documentation for JSAPI. Out of date content makes me sad, as a member of the docs team and someone who craves completeness in all things.
>
> The first thing to get into is a real evaluation of whether or not nuking the existing content from orbit is actually the best way to begin.
>
> If it is, I would still recommend archival instead of deletion, so any still-useful tidbits can be copied and pasted.
>
> But that is still a drastic choose of action, so I'd love to learn more.
>

It would be drastic and from a users perspective not sensible since the code itself isn't documented, at least mozjs-3.1.2.0 is not in the sense of a formal API documentation.

Unfortunately the documentation as posted on the net is very ragged; some of it long deprecated and some appears to be in transition, but it seems necessary at this point since it is what is available.

This really points to he value of formally documented header files. The documentation accompanies the library when installed and anytime an interface is changed a programmer can change the documentation as well. There's something to be said for using Doxygen.
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Jason Orendorff-2
In reply to this post by Eric Shepherd
On Sun, Mar 8, 2015 at 6:23 PM, Eric Shepherd <[hidden email]> wrote:

>
> I'd love to have a real discussion about how to get properly up to date
> documentation for JSAPI.


Agreed! Let's talk!


> Out of date content makes me sad, as a member of the docs team and someone
> who craves completeness in all things.
>
> The first thing to get into is a real evaluation of whether or not nuking
> the existing content from orbit is actually the best way to begin.
>
> If it is, I would still recommend archival instead of deletion, so any
> still-useful tidbits can be copied and pasted.
>
> But that is still a drastic choose of action, so I'd love to learn more.
>

OK. Here's how I perceive the current situation:

The documentation is uneven. Despite heroic efforts by arai, Ms2ger, and
evilpie, many features of the API are not documented at all, a great deal
of what's there is flagged as in need of technical review, some of it is
obsolete. Using the API strictly based on the docs would be virtually
impossible. When I hear that the first example program in the JSAPI User
Guide doesn't compile, it is no surprise and I don't have time to go fix
it. All this has been the case for years. I think the JSAPI documentation
is a source of frustration for everyone who encounters it; though
admittedly maybe there are some happy customers somewhere I don't know
about. It's certainly a source of frustration for me.

What are the underlying causes here?

1.  Nobody knows what is current and what needs work. There is no way to
tell.

2.  We don't have the time to do the work. It is simply a fact that
third-party software using the JS engine as a library is not a priority for
us at all.

I see no solution to either issue as long as the API reference is in MDN as
ordinary content. What we are doing will never produce documentation that's
good enough end-to-end. The API reference will be out of date as long as
it's not autogenerated from comments in our code. Code samples will be out
of date as long as they're not in-tree and subject to automated testing.

I'm very tired of seeing people suffering due to this bad resource. In my
opinion, it should all be mass-archived immediately.

The people who have worked on the MDN JSAPI docs are talented, sharp
people. If you're one of them and you've read this far, I'd love to seem
you devoting that time to solving the problem in a more permanent way---by
Doxygenating our headers, importing documentation into the source tree, and
getting it under test coverage.

-j
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Boris Zbarsky
In reply to this post by Eric Shepherd
On 3/9/15 1:52 PM, Jason Orendorff wrote:
> I see no solution to either issue as long as the API reference is in MDN as
> ordinary content. What we are doing will never produce documentation that's
> good enough end-to-end. The API reference will be out of date as long as
> it's not autogenerated from comments in our code.

So one problem we should think about is which API version should be
documented (or more than one)?

Put another way, if I land an API change, should that change the MDN
docs immediately to show the new API, change them to show the old API
until version X then the new API, not change them until my changeset is
shipped (in what?  Firefox release, ESR, SpiderMonkey release, something
else?), or something else?

-Boris
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Jason Orendorff-2
On Mon, Mar 9, 2015 at 2:05 PM, Boris Zbarsky <[hidden email]> wrote:

> On 3/9/15 1:52 PM, Jason Orendorff wrote:
>
>> I see no solution to either issue as long as the API reference is in MDN
>> as
>> ordinary content. What we are doing will never produce documentation
>> that's
>> good enough end-to-end. The API reference will be out of date as long as
>> it's not autogenerated from comments in our code.
>>
>
> So one problem we should think about is which API version should be
> documented (or more than one)?
>
> Put another way, if I land an API change, should that change the MDN docs
> immediately to show the new API, change them to show the old API until
> version X then the new API, not change them until my changeset is shipped
> (in what?  Firefox release, ESR, SpiderMonkey release, something else?), or
> something else?
>

Here's what Python does:

    https://docs.python.org/3.4/
    https://docs.python.org/3.3/
    https://docs.python.org/2.7/

Once documentation is autogenerated, it's quite easy to generate the docs
for any given branch: check out that branch and run the script.

-j
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Fwd: JSAPI User Guide out of date

Sean Stangl
We should check with the MDN people to see whether there's any precedent
for doing documentation builds from the tree. I'm not sure how a script
would automatically update the wiki format, so we'll probably have to
collaborate on process.

On Tue, Mar 10, 2015 at 9:26 AM, Jason Orendorff <[hidden email]>
wrote:

> On Mon, Mar 9, 2015 at 2:05 PM, Boris Zbarsky <[hidden email]> wrote:
>
> > On 3/9/15 1:52 PM, Jason Orendorff wrote:
> >
> >> I see no solution to either issue as long as the API reference is in MDN
> >> as
> >> ordinary content. What we are doing will never produce documentation
> >> that's
> >> good enough end-to-end. The API reference will be out of date as long as
> >> it's not autogenerated from comments in our code.
> >>
> >
> > So one problem we should think about is which API version should be
> > documented (or more than one)?
> >
> > Put another way, if I land an API change, should that change the MDN docs
> > immediately to show the new API, change them to show the old API until
> > version X then the new API, not change them until my changeset is shipped
> > (in what?  Firefox release, ESR, SpiderMonkey release, something else?),
> or
> > something else?
> >
>
> Here's what Python does:
>
>     https://docs.python.org/3.4/
>     https://docs.python.org/3.3/
>     https://docs.python.org/2.7/
>
> Once documentation is autogenerated, it's quite easy to generate the docs
> for any given branch: check out that branch and run the script.
>
> -j
> _______________________________________________
> dev-tech-js-engine mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-tech-js-engine
>
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Jason Orendorff-2
Two ideas:

1. See js/src/doc/README.md

2. It would not be crazy to just post SpiderMonkey docs to readthedocs.org
or some such thing instead. MDN is the perfect place for Web-facing APIs,
but searching for "constructor" on MDN also finds hits like
JS_GetConstructor and JS_NewObjectForConstructor. Maybe that is actually
not a good thing. (?)

-j


On Wed, Mar 11, 2015 at 3:44 PM, Sean Stangl <[hidden email]> wrote:

> We should check with the MDN people to see whether there's any precedent
> for doing documentation builds from the tree. I'm not sure how a script
> would automatically update the wiki format, so we'll probably have to
> collaborate on process.
>
> On Tue, Mar 10, 2015 at 9:26 AM, Jason Orendorff <[hidden email]>
> wrote:
>
> > On Mon, Mar 9, 2015 at 2:05 PM, Boris Zbarsky <[hidden email]> wrote:
> >
> > > On 3/9/15 1:52 PM, Jason Orendorff wrote:
> > >
> > >> I see no solution to either issue as long as the API reference is in
> MDN
> > >> as
> > >> ordinary content. What we are doing will never produce documentation
> > >> that's
> > >> good enough end-to-end. The API reference will be out of date as long
> as
> > >> it's not autogenerated from comments in our code.
> > >>
> > >
> > > So one problem we should think about is which API version should be
> > > documented (or more than one)?
> > >
> > > Put another way, if I land an API change, should that change the MDN
> docs
> > > immediately to show the new API, change them to show the old API until
> > > version X then the new API, not change them until my changeset is
> shipped
> > > (in what?  Firefox release, ESR, SpiderMonkey release, something
> else?),
> > or
> > > something else?
> > >
> >
> > Here's what Python does:
> >
> >     https://docs.python.org/3.4/
> >     https://docs.python.org/3.3/
> >     https://docs.python.org/2.7/
> >
> > Once documentation is autogenerated, it's quite easy to generate the docs
> > for any given branch: check out that branch and run the script.
> >
> > -j
> > _______________________________________________
> > dev-tech-js-engine mailing list
> > [hidden email]
> > https://lists.mozilla.org/listinfo/dev-tech-js-engine
> >
> _______________________________________________
> dev-tech-js-engine mailing list
> [hidden email]
> https://lists.mozilla.org/listinfo/dev-tech-js-engine
>
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Bobby Holley-2
On Wed, Mar 11, 2015 at 3:45 PM, Jason Orendorff <[hidden email]>
wrote:

> 2. It would not be crazy to just post SpiderMonkey docs to readthedocs.org
> or some such thing instead. MDN is the perfect place for Web-facing APIs,
> but searching for "constructor" on MDN also finds hits like
> JS_GetConstructor and JS_NewObjectForConstructor. Maybe that is actually
> not a good thing. (?)
>

+1. In practice, I don't think the MDN doc team should be spending time
maintaining spidermonkey docs - the embedding audience is basically
orthogonal to the web and extension developer audience that MDN is aimed at.
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine
Reply | Threaded
Open this post in threaded view
|

Re: JSAPI User Guide out of date

Ms2ger
In reply to this post by Sean Stangl
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 03/11/2015 11:45 PM, Jason Orendorff wrote:

> Two ideas:
>
> 1. See js/src/doc/README.md
>
> 2. It would not be crazy to just post SpiderMonkey docs to
> readthedocs.org or some such thing instead. MDN is the perfect
> place for Web-facing APIs, but searching for "constructor" on MDN
> also finds hits like JS_GetConstructor and
> JS_NewObjectForConstructor. Maybe that is actually not a good
> thing. (?)

FWIW: https://gecko.readthedocs.org/en/latest/

Ms2ger

-----BEGIN PGP SIGNATURE-----

iQEcBAEBAgAGBQJVAM3CAAoJEOXgvIL+s8n2U6AH/Rbwif5Iw5y4tblaYMKxqPTw
TVF/Ztvg022CQdHPdnFDhiEa8mQkmXQGKis7isOqZIPYCUZeNLPwpXvM1FFgVnE1
fU3d/4m6TJRsHnBYbjYxqAC3id32/xLzUWUjQom0uRaW1uf6R8uUx9In8IMbcAYV
9DS8up4DW81RkCy9st1JTf8+G5S4kqFlvtDghJ9p8a/qjY39k6kxfdjfeXqKZf4S
xOASKoG9vuhCDbEvDiFnI1OZCKkk3lULgLbybr9PkFKTluN6wb8O35YaDh4cc/SK
7ZU6uDcOfkhfQ0bLpUGPmQ3UJ63U82l78Yad/rkSbC9V0SDhHk9VHDS3w7uhczg=
=dWxe
-----END PGP SIGNATURE-----
_______________________________________________
dev-tech-js-engine mailing list
[hidden email]
https://lists.mozilla.org/listinfo/dev-tech-js-engine