Improve documentation around func and method

[PMunch]

There has been a couple questions about the difference between func and proc over on IRC lately, so I decided to try to improve the documentation for those.

[ringabout]

Fyi, the CI failure is caused by #19132 (comment)

[demotomohiro]

Maybe explaining "function always returns same output from same input and return value, var and ref arguments are output" helps people understanding about a function.

[PMunch]

I considered it, but was unsure how much I should go in-depth about the concept of functions in such a beginner-oriented tutorial. I opted instead to mention that this was the concept of functional/mathematical functions.

[ZoomRmc]

...in such a beginner-oriented tutorial. I opted instead to mention that this was the concept of functional/mathematical functions.

In fact, this is the part of text which bothers me the most. I see a tiny contradiction here, as we don't expect the reader to thoroughly understand the concept while describing it in opaque way. This will repel readers from using funcs, instead of encouraging them.

[ZoomRmc]

This is an attempt to mention some advantages of using functions while touching upon the concepts of mutability and control flow.

This could greatly benefit from some footnotes. Do we have a policy for those? I see no external links in the file besides the "several other resources for learning Nim" in the intro.

[ZoomRmc]

Suggested change

	Functions are closer to the concept of a pure mathematical
	function, which might be familiar to you if you've ever done functional
	programming. Essentially they are procedures with additional limitations set on
	them: they can't access global state (except `const`) and can't produce
	side-effects. The `func` keyword is basically an alias for `proc` tagged
	with `{.noSideEffects.}`. Functions can still change their mutable arguments
	however, which are those marked as `var`, along with any `ref` objects.
	Functions are essentially procedures with additional limitations set on them:
	they can't access global state (except `const`) and can't produce side-effects.
	This puts Nim functions closer to the concept of a mathematical function, which
	might be familiar to you if you've ever done functional programming. The main
	benefit of the imposed limits is that it's much easier to reason about the code
	with minimized interdependence of its various parts, as data flows directly
	through a function from its arguments to its output. The other notable advantage
	is that the self-contained nature of a function makes it inherently more
	portable and easier to test.
	Even though these benefits apply to Nim functions, it's important to keep in
	mind that a `func` can still change its mutable arguments: those marked as `var`
	along with `ref` objects (which possess interior mutability). This still allows
	functions to have additional outputs beside the return value, making them not as
	"pure" as their mathematical counterparts.
	Technically, the `func` keyword is a shorthand alias for `proc` tagged with
	`{.noSideEffects.}`.

[konsumlamm]

One small typo: it's "possess", not "posses".

[Araq]

I'm merging it this time for the sake of moving on, but tutorials work better when they're short. "Person X had trouble on IRC" is not a reason for a change. "N persons had trouble on IRC" is a reason.

[ZoomRmc]

I'm merging it this time for the sake of moving on, but tutorials work better when they're short. "Person X had trouble on IRC" is not a reason for a change. "N persons had trouble on IRC" is a reason.

@Araq, could you clarify, are you saying my suggestion above falls in the too long category for you?
And the second question is our documentation policy for footnotes linking to third-party sources (wiki, papers, etc).

In my opinion, there's no point in strictly limiting what we can teach people in the tutorials as long as it's correct and applicable to the main topic. And as soon as it gets too long or complicated (there we could judge by the IRC complaints), it's not too hard to split the material to a dedicated document, compared to writing it anew. This way we can grow the documentation/learning materials in a "snowflake" manner.

If, for example, we mentioned mutability too much in this tutorial (and we haven't yet), we could just extract it all in a separate explainer (which was suggested by mratsim #8370 (comment))

[PMunch]

...in such a beginner-oriented tutorial. I opted instead to mention that this was the concept of functional/mathematical functions.

In fact, this is the part of text which bothers me the most. I see a tiny contradiction here, as we don't expect the reader to thoroughly understand the concept while describing it in opaque way. This will repel readers from using funcs, instead of encouraging them.

I actually thought about rewriting it to not say that they have limitations but rather saying that they have stronger safety guarantees or something like that. They are more limited, yes, but that is a feature.

I'm merging it this time for the sake of moving on, but tutorials work better when they're short. "Person X had trouble on IRC" is not a reason for a change. "N persons had trouble on IRC" is a reason.

This wasn't "person X had trouble on IRC" though, I have observed at least three people now with questions regarding func. And in general it is a feature that many users simply aren't aware of. Just wanted to highlight that Nim has a difference between method, proc, and func in case people from other languages are confused. But I tried to keep it brief as not to expand the section too much (this should be kept somewhere else, just not exactly sure where).

EDIT: I also agree with @ZoomRmc that we could definitely use a couple separate articles on some of the more complex features/facets of Nim. It is a language that does things a bit different from what many are used to (in a good way in my opinion), but some of these things definitely need a bit of explaining to get right.

[Araq]

@Araq, could you clarify, are you saying my suggestion above falls in the too long category for you?

Probably, yes.

And the second question is our documentation policy for footnotes linking to third-party sources (wiki, papers, etc).

Footnotes are annoying on a webpage, IMO. And yeah, we don't link to third-party sources, our readers are potential programmers and are assumed to know how to Google terms.

In my opinion, there's no point in strictly limiting what we can teach people in the tutorials as long as it's correct and applicable to the main topic. And as soon as it gets too long or complicated (there we could judge by the IRC complaints), it's not too hard to split the material to a dedicated document, compared to writing it anew. This way we can grow the documentation/learning materials in a "snowflake" manner.

In my opinion, we should respect the reader's time and focus on the topic at hand.

If, for example, we mentioned mutability too much in this tutorial (and we haven't yet), we could just extract it all in a separate explainer (which was suggested by mratsim #8370 (comment))

Well, we're not Wikipedia and there is such a thing as "too much information". It can also be discouraging.

[ZoomRmc]

Ok, understood. Spared me of making a separate PR with the above suggestion and other additions.

our readers are potential programmers and are assumed to know how to Google terms.
we should respect the reader's time and focus on the topic at hand.
we're not Wikipedia and there is such a thing as "too much information".

Well, the topic is introducing the language and its features. The assumed audience is newcomers and beginners. We explain there are some things in the language but don't give enough advice on which and how to use. Using Wikipedia is fine, but first of all, the info there is generalized for all audiences (and CS topics are not explained well for non-specialists) and also has too much information not related to Nim. We have an opportunity to explain things in a focused (on how they work in Nim) way. This is very valuable and only very large amount of googling can constitute that.

Again, as long as we have a place to move them to, all excessive info can be split later. Turning info down on input is premature optimization, and you have no benchmarks supporting this (i.e. people complaining the tutorials are tedious).

Also, for those short on time we have at two links in the beginning.

[Araq]

Newcomers to Nim are not necessarily newcomers to programming.

Again, as long as we have a place to move them to, all excessive info can be split later. Turning info down on input is premature optimization, and you have no benchmarks supporting this (i.e. people complaining the tutorials are tedious).

Also, for those short on time we have at two links in the beginning.

nim-lang/website#318

But I think I need no evidence for "excessive amout of X can be overwhelming".

[ZoomRmc]

The #318 is more about structure than the contents, and it's very likely the proverbial sample of 1.

But if you believe you have enough evidence that tutorials are already (or will be after some small additions) excessive, then I have no further arguments. Perhaps, we should start taking stuff out of them then.

[Araq]

I checked it, tut1 is about 50 pages, tut2 is 20 and tut3 is 10 pages. That's not "excessive", it's fine. However, if more content is added for newcomers to programming, I think it makes sense to be very explicit about it and to create a new, separate document.