Add object ids and child control ids to information displayed by the API Viewer

[cboulanger]

Even though object ids and child controls are part of the API of a library or an application, the API consumer currently needs to read the source code to discover them, unless the developer has explicitly included them in the JSDOC comments (which is prone to obsolescence). It would be great if the API Viewer (based on compiler data) could display this information. Ideally, the compiler could pick it up from the code itself; if that is technically difficult or impossible, we could add compiler hints which are easier to maintain than plain documentation.

[johnspackman]

IMHO picking this up from the code is far too difficult to do reliably, at least not at this stage - I'm not precluding it but I'm worried that it would become a significant distraction.

I agree that child controls tend to be overlooked for documentation, and if we are to avoid the same fate for objectId's then we would have to find ways to improve this.

Perhaps the reason for this failure to document is partly due to the physical location of the @childControl comments being miles away from the actual controls - IE you have to list them in the class comment. My theory is that JSDOC is so successful because the comments are part of the thing being defined, i.e. if you had to document each function in a big comment at the top of the class file it would never be up to date.

How about if we upgrade the JSDOC so that we can insert these kinds of documentation in the middle of a function? For example:

    // overridden
    _createChildControlImpl : function(id, hash)
    {
      var control;

      switch(id)
      {
        /** @childControl label {qx.ui.basic.Label} label part of the atom */
        case "label":
          control = new qx.ui.basic.Label(this.getLabel());
          /* ... snip ... */
          break;

        /** @childControl icon {qx.ui.basic.Image} icon part of the atom */
        case "icon":
          control = new qx.ui.basic.Image(this.getIcon());
          /* ... snip ... */
          break;
      }

      return control || this.base(arguments, id);

The above code is taken from qx.ui.basic.Atom - notice how the convention has been to mark the method just as // overridden and the @childControl was required to be done at the top of the class.

If we did the same for @objectId we'd have code like this:

    _createObjectImpl: function(id) {
      switch(id) {
      /** @objectId container {qx.ui.container.Composite} the root container for this editor */
      case "container":
        var comp = new qx.ui.container.Composite(new qx.ui.layout.Grid(5, 2));
        
        comp.add(new qx.ui.basic.Label("Title"), { row: 0, column: 0 });
        comp.add(this.getObject("cboTitle"), { row: 0, column: 1 });
        
        comp.add(new qx.ui.basic.Label("Name"), { row: 1, column: 0 });
        comp.add(this.getObject("edtName"), { row: 1, column: 1 });
        return comp;
        
      /** @objectId cboTitle {qx.ui.container.SelectBox} drop down for person's title, mr/mrs/etc */
      case "cboTitle":
        return new qx.ui.form.SelectBox();
        
      /** @objectId ctlrTitle {qx.data.controller.List} the controller for `cboTitle` */
      case "ctlrTitle":
        var ctlr = new qx.data.controller.List(null, this.getObject("cboTitle"), "name");
        return ctlr;

[cboulanger]

This might be useful: https://github.com/tj/dox