Partial documentation inheritance

[M-Kusumgar]

Is there a way to do partial inheritance of documentation from a class? For example:

/**
 * This is the Foo class
 *
 * @typeParam A foo type
 */
class Foo<A> {
  constructor(public foo: A) {}
}

/*
 * This is the Bar class
 *
 * {@inheritDoc Foo}
 */
class Bar<A> extends Foo<A> {}

shows a warning that the summary of the bar class will be overwritten, and it produces "This is the Foo class" as the summary for the Bar class, is there a way to show "this is the Bar class" for the Bar class summary and only inherit typeParams?

It would also be nice to do something like this:

/**
 * This is the Foo class
 *
 * @typeParam A foo type
 */
class Foo<A> {
  constructor(public foo: A) {}
}

/*
 * This is the Bar class
 *
 * {@inheritDoc Foo}
 * @typeParam B bar type
 */
class Bar<A, B> extends Foo<A> {
  constructor(public bar: B) {}
}

and be able to merge and override typeParams

Alternatively a documentation variable could also solve the problem sufficiently. For example something along the lines of

/**
 * @variabledef AType foo type
 */

/**
 * This is the Foo class
 * 
 * @typeParam A {@variable AType}
 */
class Foo<A> {
  constructor(public foo: A) {}
}

/*
 * This is the Bar class
 *
 * @typeParam A {@variable AType}
 * @typeParam B bar type
 */
class Bar<A, B> extends Foo<A> {
  constructor(public bar: B) {}
}

Kind of like a macro where it just copies and pastes text in place

Thank you!

[Gerrit0]

There isn't a way to do this today built in, you could use typedoc-plugin-replace-text to do a variables-like idea.

I've considered a @copyDoc tag before which behaves similarly to this, but haven't built it because it would only be recognized by TypeDoc, and I really don't want to encourage people to write docs in a way which results in a degraded experience for people referencing the library's declaration file, which in my experience is the primary (beating out any level of curated docs site) way that people will interact with documentation for a library. The @copyDoc tag could be implemented by a plugin (likely starting with the replace text plugin as it mostly does everything necessary already.) If someone built such a plugin, and it got a lot of use, I'd consider including it in TypeDoc itself

[M-Kusumgar]

awesome thank you so much, the replace text plugin should suffice temporarily, i would potentially be interested in creating a copyDoc plugin when i have a bit of time and use that in our project

[M-Kusumgar]

hey following this up, ive made the first iteration of this plugin here: https://github.com/reside-ic/typedoc-plugin-copy-doc

could you take a brief look at this and see if it is satisfactory. I have copied and pasted a bit of code from the typedoc code base but i have given credit and linked to the line where I got those functions from (they were not exported but used in the implementation of inheritDoc which I was mirroring so I found them helpful)

I diverged a little bit from the strategy of the replace text plugin, i thought the inherit doc plugin was more aligned with what i wanted to achieve

I plan on adding a bit of testing once i have a bit more free time and come extra configuration options that let you customise its behaviour

if all is good we could potentially add it to the list of plugins in the typedoc documentation?

[Gerrit0]

The keywords you added in reside-ic/typedoc-plugin-copy-doc@f5269c2 will make it show up on the site automatically when it rebuilds tonight (though you don't need both typedoc-plugin and typedocplugin), a quick pass makes it look pretty reasonable to me!

[M-Kusumgar]

ahhh okay perfect, thanks!