New Docs: Updated templates with old design.

[mrdoob]

Related issue: #30748

Description

Trying to get JSDoc to produce a design more similar to what we had.

Before	After

For comparison: https://threejs.org/docs/?q=icosahedron#api/en/geometries/IcosahedronGeometry

[mrdoob]

@Mugen87 I'm seeing a lot of repetition about what the methods return:

Is this intended?

[mrdoob]

I guess there's also a bug where JSDoc assumes a method is (nullable) because it can return null. I'll fix that.

[Mugen87]

Is this intended?

In the default template, there is type information in the signature and the types are mentioned in the descriptive text. That should be as excepted.

[mrdoob]

I understand that technically it's expected.

But I don't think it's ideal to have all that duplication in the docs.
It's not very nice to make users read things twice.

Do you known how/where can we fix it?

[mrdoob]

Do you known how/where can we fix it?

I guess the way to solve is by removing all these redundant descriptions?

	/**
	 * Returns the current set filter.
	 *
	 * @return {?AudioNode} The filter.
	 */
	getFilter() {

		return this.filter;

	}

If so, I can make the AI do it.

[Mugen87]

I would recommend to keep the JSDoc markup standard and update the template instead. It should be possible to update the template such that method signatures document no return types. Meaning everything behind the : would be removed. For that, I believe addSignatureReturns() returns needs an update.

three.js/utils/docs/template/publish.js

Line 189 in cbc975b

function addSignatureReturns( f ) {

[mrdoob]

I'm not sure we are talking about the same thing.

Could you elaborate?

[Mugen87]

I was assuming you wanted to remove this bit:

But now I realize I have misunderstood you, sorry.

Some methods are documented in a way such that the description and return value have similar texts. This should be mostly true for getters. If we want to avoid that, deleting or rephrasing the texts for the return values sounds good.

[mrdoob]

Okay, I'll give it a go next Monday.

There's still quite a bit of work to do for replacing the old docs. I'll push the release until they're ready.