Question 227319 in Javascript Question posted in
A very good W3school tutorial can be found here.

Javascript – How to jsdoc constructor function returning a new object properly?

For example I have a code like this:

export { createPerson }
const createPerson = (name, age) => {
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  return {
    get name() {
      return "Person name is " + name
    },
    age,
    getFullData,
  }
}

I tried to document it like this:

/**
 * @module people
 */
export { createPerson }
/**
 * Generates a new Person
 * @param {string} name Person name
 * @param {number} age Person age
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /**
   * Gets full data for this person
   */
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  /**
   * A Person
   * @constructs Person
   */
  const person = {
    /**
     * Name string
     * @type {string}
     */
    get name() {
      return 'Person name is' + name
    },
    /**
     * @prop {number}
     */
    age,
    /**
     * @method
     */
    getFullData,
  }

  return person
}

With code like this I get a proper documentation of the constructor function createPerson with the returning type link to Person, where I see all of it’s props and methods.

But I don’t see getFullData and age documentation. All @borrows variants I tryed didn’t work. @inheritdocs don’t work either. How can I get it without copying documentation? Because in a real code there are too many methods returned from the constructor and doc-copying will make a mess and it’s too ugly by it’s essence to duplicate docs.

Tags:

2

Answers


  1. Chosen as BEST ANSWER
    0

    I found a way to do what I want! It's @borrows. I just didn't read documentation carefully — that part concerning naming in JSDoc system. And here is a working solution:

    /**
 * @module people
 */
export { createPerson }

/**
 * Generates a new Person
 * @param {string} name Person name
 * @param {number} age Person age
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /**
   * Gets full data for this person
   * @returns {string}
   */
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  /**
   * @constructs Person
   * @borrows module:people~createPerson~getFullData as getFullData
   */
  const person = {
    /**
     * Name text
     * @type {string}
     */
    get name() {
      return 'Person name is' + name
    },
    /**
     * @prop {number}
     */
    age,
    getFullData,
  }

  return person
}

    Now getFullData method's documentation is inherited, but I still need to document the age prop.


  2. 0

    I would personally convert your code straight up into a class, but if you don’t want to do that you could use jsdoc to define something rather similar to a class as such:

    /**
 * @typedef {Object} Person
 * @property {string} name
 * @property {number} age
 * @property {() => string} getFullData
 */

/**
 * @param {string} name
 * @param {number} age
 * @returns {Person}
 */
const createPerson = (name, age) => {
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  return {
    get name() {
      return "Person name is " + name
    },
    age,
    getFullData,
  }
}

    If you do want to convert this to a class, I would do it like this:

    class Person {
  
  #name = '';
  age = 0;
  
  constructor( name, age ){
    
    this.#name = name;
    this.age = age;
    
  }
  
  get name(){
    
    return `Person name is ${this.#name}`;
    
  }
  
  getFullData(){
    
    return `Person ${name} is ${age} years old`;
    
  }
  
}

const createPerson = (name, age) => new Person( name, age );

    The above technique self-documents the code pretty nicely, and you could technically do away with the createPerson altogether, as it’s just new Person( name, age ), so you don’t have to add another layer of logic to create one and just export the Person class directly instead. That new operator also clearly expr4esses something will be created, so it reads kinda easy in my opinion.

    Login or Signup to reply.
Please signup or login to give your own answer.

Back To Top
Search