Clarify the use of do block with get!

[mzaffalon]

ref: https://discourse.julialang.org/t/dictionary-inverse-and-consolidating/42378/5

[KristofferC]

Not sure the extra thing about "longer than one-liner" needs to be added. The example below immediately contradicts it.

[sosiristseng]

Not sure the extra thing about "longer than one-liner" needs to be added.

Maybe just put a reference to do syntax?

Edit: https://docs.julialang.org/en/v1/base/base/#do explained the syntax already.

[sosiristseng]

Or "more-than-trivial throwaway functions". Not sure if that adds clarity or appropriate in the documentation.

[mzaffalon]

Agreed with both comments.

"This is intended to be called using do block syntax that creates an anonymous function for f::Function (see do syntax)?"

[mzaffalon]

Ops, I just wanted to comment.

[KristofferC]

Perhaps best to make this into a proper doctest?

[rfourquet]

If anything needs to be done here, I would favor removing the entire "This is intended to be called using do block syntax:" sentence. This is idiomatic Julia, I hope we will not add such a sentence to every function that supports a function as first parameter... Docstrings are not meant to replace the manual, they should be to the point, not bloated with information that belongs elsewhere.

[mzaffalon]

@rfourquet I see your point: the manual is a trove of information and the do-syntax is explained there. On the other hand, adding more information to the docstring will certainly help people who do not read the full manual before using Julia and may point them to the correct section in the manual.

A better docstring will also prevent useless posts like mine in discourse that originated this PR.

[rfourquet]

A better docstring will also prevent useless posts like mine in discourse that originated this PR.

I just had a rapid look to this discourse thread, but it seems that if the sentence related to do syntax was not there (as I suggest in the previous post), then there would not have been confusion. Sure it was an opportunity to learn about do syntax, but it's not specific to get!. Where to draw the line for what we explain in docstrings? A simple and efficient rule is to explain exactly what is specific to the documented function. I understand that for beginners it can be convenient to have redundant information, but including the definition of do blocks syntax in every docstrings of functions taking a function as first argument is a toll on every fluent Julia programmer who is fed with useless information.

[mzaffalon]

Would it make sense to leave the example with time() to show how to have a default entry that may not be constant?
get!(time, dict, key)?

Return the value stored for the given key, or if no mapping for the key is present, store key => f(), and return f().

And in this context, is it clear from the documentation that f() is not executed twice? Would "Return the value stored for the given key, or if no mapping for the key is present, store key => val, where val = f() and return val." be better?

[rfourquet]

Would it make sense to leave the example with time() to show how to have a default entry that may not be constant?
get!(time, dict, key)?

It looks fine to me to leave the current example. I would also keep it with the do syntax even if it's a contrived example, as it still suggests that do syntax is intended, and explicits that time() takes no argument, and hence that the first arg of get! is a function taking no argument. I would also put it under an # Examples heading.

And in this context, is it clear from the documentation that f() is not executed twice?

I guess it depends on the audience. It doesn't make sense to compute f() twice so this is unambiguous for me for example, but your alternate explicit formulation seems fine too.

[CameronBieganek]

Hey, I just noticed this PR. I actually submitted a similar PR (#36964) last week, and it has already been merged. However, note that the focus of the new example in #36964 is not on clarifying the do block notation but on clarifying the intended purpose of the get! function.