786280 - test documentation examples

Status: RESOLVED WONTFIX

(Add-on SDK Graveyard :: General, defect, P2)

Description

[Erik Vold [:erikvold] (please needinfo? me)]

cfx test should test the code examples used in the documentation.

Comment 1

[Erik Vold [:erikvold] (please needinfo? me)]

a check that the code is valid should be done at the least

Comment 2

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

I see a "cfx testex" in the cfx documentation: https://addons.mozilla.org/en-US/developers/docs/sdk/1.9/dev-guide/cfx-tool.html#cfx%20testex

Is that what this bug is about?

Comment 3

[Erik Vold [:erikvold] (please needinfo? me)]

Will we keep these documentation examples in our repo? perhaps we can break them out in to some other repo since the docs are going to be on MDN?

Comment 4

[Dave Townsend [:mossop]]

Which code samples are you talking about here?

Comment 5

[Erik Vold [:erikvold] (please needinfo? me)]

(In reply to Dave Townsend (:Mossop) from comment #4)
> Which code samples are you talking about here?

These https://github.com/mozilla/addon-sdk/tree/master/examples

Comment 6

[Erik Vold [:erikvold] (please needinfo? me)]

Hmm actually, when I made this bug I went purely the examples in the docs, the code snippets, iirc, but also the examples here https://github.com/mozilla/addon-sdk/tree/master/examples are referred to in the docs, but are already tested.

So what I asked in comment 3 applies to both.

Comment 7

[Dave Townsend [:mossop]]

(In reply to Erik Vold [:erikvold] [:ztatic] from comment #6)
> Hmm actually, when I made this bug I went purely the examples in the docs,
> the code snippets, iirc, but also the examples here
> https://github.com/mozilla/addon-sdk/tree/master/examples are referred to in
> the docs, but are already tested.
> 
> So what I asked in comment 3 applies to both.

I would say that the docs samples remain in MDN and the example add-ons in our repo, since we have tests for them, but I'm open to alternatives. What do you think Will?

Comment 8

[Will Bamberg [:wbamberg]]

 (In reply to Dave Townsend (:Mossop) from comment #7)
> (In reply to Erik Vold [:erikvold] [:ztatic] from comment #6)
> > Hmm actually, when I made this bug I went purely the examples in the docs,
> > the code snippets, iirc, but also the examples here
> > https://github.com/mozilla/addon-sdk/tree/master/examples are referred to in
> > the docs, but are already tested.
> > 
> > So what I asked in comment 3 applies to both.
> 
> I would say that the docs samples remain in MDN and the example add-ons in
> our repo, since we have tests for them, but I'm open to alternatives. What
> do you think Will?

Yes, I'd agree with that. At least, that the code samples embedded in the docs will move to MDN, and will not have tests written for them (although I would love this to be possible).

As far as the example add-ons in /examples, we could move them to a new repo along with their tests or keep them where they are, I'm agnostic about that.

I would question how much value they actually add, since they haven't been actively maintained in years. Do we think people really use them or even know that they exist? I think we should either just remove them or look after them better - add more examples, and make them more accessible.

Comment 9

[Irakli Gozalishvili [:irakli] [:gozala] [@gozala]]

(In reply to Erik Vold [:erikvold] [:ztatic] from comment #3)
> Will we keep these documentation examples in our repo? perhaps we can break
> them out in to some other repo since the docs are going to be on MDN?

I'd be down with moving into separate repo, my only worry is we may break them and not even notice
breaking them. If they were still tested on tbpl I guess that wouldn't be a big issue then.

I also do think we should be writing a lot more examples, in fact we should have at least on example per
API, I would even say it should be as important as writing tests.

Comment 10

[Erik Vold [:erikvold] (please needinfo? me)]

Sorry we won't be releasing any new versions of cfx, jpm is the replacement https://www.npmjs.com/package/jpm

We can do this with jpm however.