Docs: Visible type information.

[donmccurdy]

This came up in an issue at one point, so thought I'd suggest a way of displaying type information in the docs. This just covers BufferGeometry, but I can update other pages if the approach is agreeable. PR now covers all pages. Method/property names would now use their own permalinks, with type information in a low-contrast color afterward.

Demo — All docs

Screenshot

[mrdoob]

That looks great to me! 👍👍👍

[WestLangley]

I do not think the foreground/background contrast, as proposed, is sufficiently legible.

There are metrics for these things, but I expect someone could select reasonably-high-contrast colors and they would be fine.

[donmccurdy]

Pushed an update with higher contrast, matching the comments in our code blocks. I'll wait to update other pages until after r90 to avoid drift/conflicts on the PR and to get any other feedback.

[WestLangley]

Pushed an update with higher contrast

I think a different color scheme for the entire document is in order, quite frankly. I vote for clearly legible.

[donmccurdy]

Let's address that in another PR — showing type information at all, with the same legibility as example comments (slightly more legible, actually, since the background is lighter), is an improvement on hover-text-only, especially for touchscreen users. 🙂

[looeee]

This is awesome! 😄

[donmccurdy]

A few prayers to the regex gods later, this PR should cover all of the docs now. 😅

[takahirox]

I'm sure this change is very helpful to users.

One thing, "return value type null" for the methods returning nothing would be a bit misleading. So should be like this?

.dispose () : nothing
.dispose () : undefined
.dispose () :

This seems existing issue, so another PR would be good.

[donmccurdy]

Good point. Hiding the return type when there is no return value seems cleanest. Updated.

[Mugen87]

One minor thing. It seems that syntax highlighting is broken:

It should look like this:

[mrdoob]

I don't think we need this line. What's wrong with showing : null?

[mrdoob]

Lets remove this line and the PR will be good to go.

[donmccurdy]

✅

[donmccurdy]

One minor thing. It seems that syntax highlighting is broken:

Strange... I think that's caused by Rawgit — there are errors on the console about MIME types of the code highlighting CSS. It works when serving the dev branch, but perhaps can't do the same from secondary branches? E.g. this older branch shows the same issue.

---

@mrdoob I think you left a comment about handling null returns more simply, but I can't find it inline, maybe GitHub is struggling with the large diff... Just guessing here, we could change all [member:name title] entries inline to something more like:

[member:title] () : [return:name]

... where the : [return:name] portion is omitted for methods returning null. I think that would result in 1 fewer lines of code, because the [member:name] to [member:name title] regex could be removed. Preference?

EDIT: Oh there's your comment 😅 yeah i'm fine with leaving : null in, too. Technically we are not returning null, but it's clear enough that I don't have a preference really.

[mrdoob]

When a method return null tends to have a reason. If anything... I would hide the return part when a method returns undefined as that is the default.

[donmccurdy]

Codebase has 357 matches for [method:null and none for [methed:undefined. I think we've used null in all of the cases where nothing is returned, too, so I can't differentiate here without going through method by method. 😕

[takahirox]

Personally I wanna be strict with value type representation as much as possible so I wanna distinguish between return null and return nothing.

But, as I said, we can leave : null so far and fix that in another PR (if necessary). The main purpose of this PR is making value type visible in doc, not updating return value type. And updating would take time because we can't automatically differentiate them, perhaps we need to update by hand.

[mrdoob]

But, as I said, we can leaving : null so far and fix that in another PR (if necessary).

Yes please.

[donmccurdy]

Sounds good, removed the line. Glad to consider other changes in another PR. 👍

[mrdoob]

Thanks!

[mrdoob]

After this PR, I guess the # link in the right side of every property/method is no longer needed?

[donmccurdy]

Not functionally necessary, no. I like the pattern where the # appears to the left when you hover over a title, just as a clue it's a permalink. But either way.