Improve shader function descriptions

[AshbyGeek]

Adds much detail to the documentation on built-in shader functions, copied from (with a few modifications) and linked to official GLSL documentation.

That documentation was moved into a separate file due to its verbosity, and organized into smaller sections following the organizational comments in https://github.com/godotengine/godot/blob/master/servers/rendering/shader_language.cpp.

Style tries to generally follow the styling used in class documentation, but differences between .gdshader and .gdscript meant some changes had to be made.

[AshbyGeek]

Pull request for issue #9310

[skyace65]

CC @clayjohn

[clayjohn]

That was unbelievably fast. I'm going to need a few days to review this. But I am very excited!

[AThousandShips]

This looks good, gonna go through it for style again but this was some that stuck out for now

[clayjohn]

Amazing work! This looks really good so far.

I think I just have two general comments:

1. I agree with Chaosus' comment earlier that, in most cases, functions with the same name should be grouped instead of duplicated. Especially for functions with really long descriptions.
2. I like how you kept the short description in the table. But I think it needs to be truly a short description. Some of the entries have the entire description copied in the table and that ends up making the table bloated in hard to navigate.

See DfDx for example

In these cases, the table actually has more information than the long description below.

[AshbyGeek]

Awesome! I'm glad you like it. I'm pushing hard to finish a project milestone this week, but I should be able to work on an update next week.

[skyace65]

Did a grammar and spelling check and everything looks good.

[tetrapod00]

I didn't do a whole review, but I skimmed and caught some typos.

I also noticed no consistency of "Return" vs "Returns" or "Calculate" vs "Calculates" in the descriptions of functions, but I don't think that's really worth the effort to standardize.

[AshbyGeek]

@tetrapod00 Any thoughts on the conversation @clayjohn and I were having about functions working on arrays piecewise?

[AshbyGeek]

Latest commit addresses concerns about component-wise functions and operators. It also improves some formatting and fixes some oddities with the navigation tree. Here's a bulleted list of what I changed:

• Use appropriate header so that the navigation tree will work correctly (accidentally used some subsubheaders I think)
• Make the classref-method styling apply to entries with multiple overloads
• Use a single table row for entries with multiple overloads
• 2nd column of each table disables text wrapping (had to add to static/custom.css) so that table rows with multiple entries will keep those entries aligned with their return types
• Fixed some function names in the descriptions that weren't bold
• Fixed a couple entries that failed to include the on-hover tooltip for vec_type
• Improve wording of note about operators being piece-wise and move it to underneath the actual operators
• Improve wording of note about functions being piece-wise

[AThousandShips]

Otherwise I think this looks good

[tetrapod00]

I see a lot of places where style can be improved in a minor way, like styling literals as code and with a decimal marker for floats (e.g. 0.0 instead of 0 or "0.0" for a float value of 0). I'll do a detail-oriented review on this (or a followup PR if we'd rather not block merging).

[tetrapod00]

I started on a nitpicky style review but I think it would be better as a followup PR - making all the required changes is annoying as suggestions.
It's a lot of stuff like:
"if x < -1" vs "if x is less than 0.0" vs "if x ≤ 0"
(e^x + e^-x)/2 vs "x=2\ :sup:y"
This stuff should be standardized, and I can do the work, but it will be annoying to do as a bunch of individual suggestions on the web UI.

IMO the style inconsistency is not bad enough to prevent merging as is.

[AshbyGeek]

Ok, fixed the couple things you already mentioned since I needed to fix my GLSL 4.0 mistake. I'm more than happy to let you fix the rest of the tedious formatting issues in another PR.

What does the merge process look like from here? We wait for ClayJohn or some such to come give a final approval and pull it in?

[tetrapod00]

Yeah, now you're waiting on another review from clayjohn or someone else with shader-specific knowledge to do a high-level review including whatever other style nitpicks come up in that review, then it should be merge-able. IMO this PR is already so much better than the current state of the function docs that this PR is merge-able as-is.

(Also I believe in most cases we would address the style consistency in this PR, not a followup, but it is really tedious work on a large PR, it's not blocking, and I'm volunteering to do it)