Wrong hierarchy infering

[matteodelabre]

Consider the following file:

/**
 * A global Parent
 *
 * @var {object}
 */
var Parent = {};

/**
 * An enumeration of values
 *
 * @readonly
 * @enum {number}
 */
Parent.enum = {
    /** First doc block */
    Parent: 1,

    /** Second doc block */
    Child: 2
};

With output formats that support hierarchy, such as html, the infered hierarchy for this code is wrong. There are two special cases in this code. First, the enumeration is imbricated into another object, and second, a child symbol has the same name as the parent object, which is perfectly legal in JS.

However, this situation is not handled correctly by documentation, because the algorithm that calculates the hierarchy is flawed.

This algorithm (https://github.com/documentationjs/documentation/blob/master/streams/hierarchy.js#L36) creates a lookup index based on the names of the symbols, wherever they are in the tree, so we end up with an index looking like this, at line 51:

nameIndex = {
    enum: {description: 'An enumeration of values', ...},
    Parent: {description: 'A global parent', ...},
    Child: {description: 'Second doc block', ...}
};

First problem, the first doc block doesn't appear in the index. This problem is not really important in this case, it doesn't hold any child, but it would be if it would.

Second problem, Parent.enum.Parent and Parent.enum.Child have an infered @memberof value that is Parent.enum (because the left-hand side of the assignment is Parent.enum), but this string is not present in the index, so the algorithm doesn't find the symbol in the index, throwing the following errors:

index.js:18: memberof reference to Parent.enum not found
index.js:15: memberof reference to Parent.enum not found

And we end up with the following hierarchy, which is wrong.

├─ Parent (A global Parent)
│  └─ enum (An enumeration of values)
├─ Parent (First doc block)
└─ Child (Second doc block)

While the following hierarchy would be correct.

└─ Parent (A global Parent)
   └─ enum (An enumeration of values)
      ├─ Parent (First doc block)
      └─ Child (Second doc block)

[anandthakker]

@MattouFP Nice catch, and thanks for the careful report.

[tmcw]

Looking into this over this weekend, tinking in the rclark-sorting branch.

As far as the

var foo = {
  bar: {
    baz: {}
  }
};

Case, this membership code doesn't seem to 'look up' far enough to catch this case. We infer membership before hierarchy and likely need to flip this, or combine the two steps to accomodate for this case. Ideas & help are much appreciated.

[vorg]

I've just run into similar issue:

/**
 * Keyboard Event class
**/
function KeyboardEvent(type, data) {
    Event.call(this, type, data);
}

/**
 * Key down event constant
 * @instance
 */
KeyboardEvent.KEY_DOWN  = 'keydown';

Will produce 2 KeyboardEvent entries:

KeyboardEvent
.KEY_DOWN
KeyboardEvent

The second entry has constructor only

I tired to use @memberof but without luck

[jfirebaugh]

We need to build a tree. Started sketching this out in https://github.com/documentationjs/documentation/tree/hierarchy.

[jfirebaugh]

Fixed in #177.