How to avoid "new" in JavaScript factory function's documentation (or a better way to document its return type)?

Question

Let's say I have a factory function like this:

function Person(name, age) {
    return {name: name, age: age};
}

Using JSDoc3, I tried to document that function in the following way:

/** Creates a Person object
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @returns {object} The Person object specified */
function Person() {...}

Obviously, this leads to the generation of the Person function's documentation as a Method and doesn't give any clues about the return object's structure.

Therefore I tried to document it as a class, like so:

/** Represents a person
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @class*/
function Person(name, age) {
    return /** @lends Person.prototype */ {
        /** The name of the person */
        name: name, 
        /** The person's age in years */
        age: age
    };
}

Unfortunately (apart from the documentation comments not being DRY), documenting it as a class will result in the following text:

Class: Person

Person

new Person(name, age) ...

Notice the new keyword there?

This is not how I intended the Person function to be called, instead I use it as in var joe = Person("Joe", 24);.

How can I get rid of the new keyword in the generated documentation?

Update

Thanks for all the ideas/suggestions in the comments below, here is some additional information to clarify a couple of things:

• I am aware that it would've probably been better to use real classes (custom objects), which do use new to create. This question however is about documenting these existing factory functions using JSDoc3 in a way that leads to a useful API reference.
• I am aware that it is technically incorrect to label the function Person with @class, as it is not used as a class (doesn't take new to create an instance). In the same way as it is technically incorrect to use @lends Person.prototype (thanks @nnnnnn for pointing this out), as the prototype of Person is not involved. Again, I did this for documentation purposes to have the fields of a person instance documented in a linkable fashion.
• As suggested by @Bálint and @nnnnnn, I could document the Person's return type (i.e. the person instance structure) within the Person's @returns tag. This puts me back to my first attempt, in which a person instance documentation is just a textual description and I am not sure I can link to its members from other points in the documentation:

If Person is documented as a @class, I can e.g. create references to a person (and its fields) documentation like so:

/** Produces an array of {@link Person}s, sorted by their {@link Person#age}.
 * @param {Array} persons The persons to sort
 * @returns {Array} The sorted persons*/
function sortPersonsByAge(persons) {
    return persons.sort(function(a, b) {return a.age - b.age;});
}

If I leave the Person's documentation as a method (as the very first attempt above) and put all the information about a person's object structure inside its @returns documentation tag, how can I link to the type and its fields/methods from elsewhere, as in the sortPersonsByAge example?

Answer 1

A solution that seems both technically correct and producing nice documentation is provided via the @typedef tag, which can be used to document the return type separately from the factory function.

Within the @typedef, the @property tag can be used to define the fields:

/** Represents a person. Use the {@link Person} function to create one.
 * @typedef PersonObj
 * @property {String} name The name of the person
 * @property {Number} name The person's age in years */

Then, a link to that type can be added to e.g. the factory function's documentation:

/** Creates a {@link PersonObj}
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @return {PersonObj} The new person object */
function Person(name, age) {
    return {
        name: name, 
        age: age
    };
}

Hope someone else finds this helpful.

Answer 2

Because my previous answer didn't lead to function members of the @typedef being documented at all, I resorted to the @namespace tag instead:

/** Creates a {@link PersonObj}
 * @param {String} name The name of the person
 * @param {Number} age The person's age in years
 * @return {PersonObj} The new person object */
function Person(name, age) {
    /** Represents a person. Use the {@link Person} function to create one.
     * @namespace PersonObj */
    return p = {
        /** The name of the person 
         * @memberof PersonObj# */
        name: name, 
        /** The person's age in years
         * @memberof PersonObj# */
        age: age,
        /** Displays a greeting 
         * @memberof PersonObj# 
         * @param {String} otherName Name of another person */
        greet: function(otherName) {
            alert('Hello '+otherName+', my name is '+p.name);
        }
    };
}

One advantage of this pattern is that the type's member documentation is now closer to where they are actually defined in the source.

One disadvantage is that the @memberof tag seems to be required for the members to show up in the documentation of the namespace.