jsdoc3/jsdoc — pull request #335 by mathematicalcoffee (2013-02-04 07:02:05+00:00)
Title: added tests for Tutorial class.

I added some tests for the tutorial class (tutorial.js).

I also came across some behaviour I'm not sure about, so want to check.

Currently, `Tutorial#addChild` and `Tutorial#removeChild` add or remove the child tutorial from `this.children`, but they *do not* set or unset `child.parent`. This can lead to some confusing behaviour. Using `setParent` appropriately sets both parent.children and child.parent.

Assume we have three tutorials, `child`, `par` and `par2`.

1. `child.setParent(par)`. This sets `child.parent = par, par.children = [child]` (good).
2. `par2.addChild(child)`. This sets `par2.children = [child]`. But now `child.parent = par` (still) and `par.children = [child]` (still).
3. `par.removeChild(child)`. Now we have `par2.children = [child], child.parent = par` and `par.children = []`, so although `par2.children` has `child` in it and `par.children` no longer does, `child.parent` is pointing to the wrong parent.

To fix this, I could just make sure that `parent.addChild(child)` not only adds `child` to `parent.children` (as it currently does), but *also* sets `child.parent = parent`.

Additionally, `parent.removeChild(child)` should not only remove `child` from `parent.children`, but *also* set `child.parent = null` (i.e. has no parent).

This does enforce that each tutorial may be the child of exactly 0 or 1 tutorials - in particular, a child cannot belong to multiple parents. But I believe this is consistent with the current behaviour, since tutorials have a *single* `.parent` property (as opposed to `.parents = []`).

If you agree with this, then I can add another commit to this pull request with the necessary modifications and additional tests for this inheritance stuff (I have it sitting in another branch of my fork waiting to go).

If not, then you are free to accept this pull request (if you like) which only adds tests for the existing behaviour and doesn't address this issue.