Add an @member tag for documenting interface members outside of the interface

[iansan5653]

Sometimes you have a generic base interface type that you extend from, and you want to documenting a member of the extending interface without having to redeclare that member. In this instance, it would be useful to be able to document interface members in the interface's description. This is better explained in an example:

/**
 * A generic building.
 */
interface Building {
  /**
   * The total area of the building in sq. ft.
   */
  area: number;
}

// Annoying and prone to breaking if the base interface changes:

/**
 * A residential house that someone might live in.
 */
interface HouseA extends Building {
  /**
   * The total area of the house in sq. ft. House area doesn't include garages,
   * attics, and basements.
   */
  area: number;
  /**
   * The number of people living in the house.
   */
  residents: number;
}

// A preferable solution:

/**
 * A residential house that someone might live in.
 * @member area - The total area of the house in sq. ft. House area doesn't
 * include garages, attics, and basements.
 */
interface HouseB extends Building {
  /**
   * The number of people living in the house.
   */
  residents: number;
}

[octogonz]

My opinion is that if we're extending the meaning of area, we should probably redeclare it:

/**
 * A residential house that someone might live in.
 */
interface HouseB extends Building {
  /**
   * The number of people living in the house.
   */
  residents: number;

  /**
   * The total area of the house in sq. ft. House area doesn't
   * include garages, attics, and basements.
   */
  area: number;
}

@member seems to go against a couple of software engineering principles:

• Reading > Writing: @member is a shorthand that saves some work for the person writing the code, but at the expense of making the code harder to read. The person needs to go find the base class to figure out what area is talking about. We should prioritize the experience of people who read code, because reading a more challenging/important activity than writing code.

• One obvious way: @member introduces with two different equivalent ways to document an inherited member. This flexibility is bad. Good flexibility is like forks versus spoons -- different tools optimized for different jobs. Bad flexibility is like Phillips screws versus flathead screws -- make everyone buy two screwdrivers for no clear benefit. 😋

I'm open to other views, though!