Drop examples from closure language reference #1975
Conversation
Relates to nushell#1929 The language reference should be focused on the language concepts, not describe how various commands make use of it, and especially not in the form of examples. All these commands have closure examples in the docs comments. All listed commands link to their respective docs. Dropping the examples increases focus of the *reference* doc, and reduces risks of doc duplication and of command changes leading to outdated lang ref docs.
|
I'm not sure I agree. I like examples as a way to help explain things. |
We are talking about the Language Guide/Reference not the general book. Examples for concepts / distinct specialties of closures yes, stamp collecting of commands that happen to use closures no. |
|
@fdncred Where do you think would be a fitting place for these kinds of or these examples specifically? Closures are documented in the Book in the Types of data section. But as a relatively concise block. https://www.nushell.sh/book/types_of_data.html#closures The language reference documents that closures exist. The fact that they can different forms and parameters is a consequence of what they are. I don't think a list of specific command examples is what should be documented here. If we want to show that there is variance, beyond just saying that there is, we can do so with two or three examples, with or without specific commands. I would certainly want to evade command headlines as if we were talking about those commands here. In terms of examples in general, those commands already have closure examples for how they are used in those commands. |
|
I'm not suggesting that it be entirely duplicated but having a couple examples and then a "to see more information on closures see some_link" would probably be helpful. |
|
Ok, I'll try to draft something |
|
I created #1982 |
Relates to #1929
The language reference should be focused on the language concepts, not describe how various commands make use of it, and especially not in the form of examples.
All these commands have closure examples in the docs comments. All listed commands link to their respective docs.
Dropping the examples increases focus of the reference doc, and reduces risks of doc duplication and of command changes leading to outdated lang ref docs.