Re: [gabriel.reid@gmail.com: Re: [Jsdoc-user] fix for objects that are extended with this.base member]

[Gabriel R. <gab...@gm...>]

Hi Justin,

>  This is a great project since it really helps Java Developers and I really 
> appreciate all of your work. I want apologize in advance for just suggesting 
> the code change without consulting you, the project owner. I was just trying 
> to prevent a lot of manual taging of classes. 

Hey, no problem with suggesting code changes! That's always welcome,
especially if it's done with justification for your changes (as you
provided).

>  Generally, there is inheritance when you set a member such as base or any 
> name and call a constructor their is a relationship established but is only 
> during the creation of the class it is not dynamic like prototype. I am not 
> sure what the original goal of how inheritance was to be displayed but maybe 
> the static inheritance could be included.
>  This document outlines this *towards the bottom of the page *
> http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:The_Employee_Example:More_Flexible_Constructors

I've realized where the miscommunication is happening now. I've been
looking for method inheritance (or maybe even general inheritance),
while you've been talking about property inheritance. Or more
specifically, only properties that are defined within a constructor. For
example, with the following code:

    function BaseClass(anId){
        this.id = anId;
    }

    BaseClass.prototype.getId(){
        return this.id;
    }

    function SubClass(anId){
        this.base = new BaseClass();
        this.base(anId);
    }


the id property is inherited, but the getId method isn't (along with
anything else that is attached to the BaseClass.prototype object). If
the base idiom is used by JSDoc to define inheritance (without doing
further checking), it would document SubClass as having a function
called getId, which would be incorrect.

This would all work fine (both in the JavaScript sense and the JSDoc
sense) if all the classes functions were defined within the constructor.
However, this is a fair bit slower (performance-wise), and it's just not
always done that way (even though it is a popular idiom).
incorrectly document SubClass as

>  The company I work for uses 100s of classes that follow this paradigm and I 
> thought this would be useful rather than making developers have to adding 
> @extends or adding to the source the prototype chain (for site speed). If we 
> don't incorporate this code I will just keep a copy with this minor change. 
> Maybe when the new parser is ready this can be easily added. 

I would be in full support of you keeping the change in your own code,
but I hope I've made it clear why I'm not so enthusiastic about adding
it to the main JSDoc code. Once I've implemented the "smarter" parser
(if that day ever comes), things like this should be taken care of
properly.

Regards,

    Gabriel


> 
>  On 9/2/05, Gabriel Reid <gab...@gm...> wrote: 
> > 
> > Hi Justin,
> > 
> > > I understand your point, maybe the base member name can be a optional
> > > parameter such as --basemembernames base,baseObj. This idiom is 
> > extremely
> > > useful especially when it is part of the coding standard. I found that 
> > when
> > > I ran our JS docs with this param I found that the tree was formed 
> > rather
> > > than requiring manual @extends keys from being added. What do you think?
> > 
> > 
> > I think that there is actually a miscommunication here. Just assigning a 
> > base
> > class constructor function to a property inside of another constructor
> > function, like this:
> > 
> > function BaseClass(pName){ this.name <http://this.name> = pName; }
> > function SubClass(){
> > this.base = BaseClass;
> > this.base("someName");
> > }
> > 
> > does not necessarily set up any kind of inheritance relationship between 
> > the
> > two classes. The inheritance relationship *is* set up when you assign an
> > instance of the base class to the subclass' prototype, as follows:
> > 
> > SubClass.prototype = new BaseClass();
> > 
> > When you use the above construction, JSDoc correctly picks up the
> > inheritance relationship without the need for the @extends tag (or at
> > least, it should pick it up!).
> > 
> > To top all of this off, I'm also looking at making the parser somewhat
> > "smarter" so that it can handle additions to the Function prototype (as
> > all "classes" are actually based on the Function class), which would
> > clear up any kind of problem such as the one we're discussing here.
> > However, that won't be coming anytime terribly soon, I'm afraid.
> > 
> > Regards,
> > 
> > Gabriel
> > 
> > >
> > > On 9/1/05, Gabriel Reid <gab...@gm...> wrote:
> > > >
> > > > On Thu, Sep 01, 2005 at 05:54:30PM -0700, Justin Early wrote:
> > > > > Hi Gabriel,
> > > > > Here is the example of a where you can use this:
> > > > > function MyBaseClass(pName)
> > > > > {
> > > > > this.name <http://this.name> <http://this.name> <http://this.name> = 
> > pName;
> > > > > this.prop1 = "test";
> > > > > }
> > > > > function MyExtendedBaseClass(pName)
> > > > > {
> > > > > //set Base class
> > > > > this.base = MyBaseClass;
> > > > > this.base(pName);
> > > > > }
> > > > > Examples are here:
> > > > >
> > > > 
> > http://developer.mozilla.org/en/docs/Core_JavaScript_1.5_Guide:The_Employee_Example:More_Flexible_Constructors
> > > >
> > > > I'm not really in favour of adding this to the code of JSDoc, as the
> > > > 'base' object isn't actually part of JavaScript or ECMAScript. 
> > Although
> > > > it's certainly a useful idiom, the 'base' object could just as easily 
> > be
> > > > called any other name and have the same effect.
> > > >
> > > > Additionally, in the example in the link that you provided, a
> > > > constructor is assigned to the prototype of a subclass, which JSDoc 
> > will
> > > > pick up and represent as subclassing.
> > > >
> > > > Regards,
> > > >
> > > > Gabriel
> > > >
> > >
> > >
> > >
> > > --
> > > It's a cool add-in for Outlook that automatically organizes your email. 
> > I
> > > think it's great!
> > >
> > > ________________________________
> > > Click http://www.caelo.com/a/rl.php3?i=U30ZD to check it out.
> > 
> 
> 
> 
> -- 
> It's a cool add-in for Outlook that automatically organizes your email. I 
> think it's great!
> 
> ________________________________
> Click http://www.caelo.com/a/rl.php3?i=U30ZD to check it out.