Update methods.md #40667
Update methods.md #40667
Conversation
As a newbie I struggled to understand the docs. I have added details that hopefully serve to clarify the issues. Please check that there are no misunderstandings on my part.
executed --> defined
doc/src/manual/methods.md
Outdated
| As you can see, the type of the appended element must match the element type of the vector it | ||
| is appended to, or else a [`MethodError`](@ref) is raised. In the following example, the method type parameter | ||
| `T` is used as the return value: | ||
| The type parameter `T` in the signature of the function ensures that appending element `x` to `v` preserves the type of the new `v`. In the function signature, `[v..., x]`, the three dots `...` stand for the regular splatting operator, while the square brackets stand for the vector with all the elements of `v` unpacked and `x` appended to it. The meaning of `{T} = [v..., x]` is that all the elements of the vector are constrained to be of the same type. Note that `{T} = v` has a different meaning as `v` refers to the container and not its elements. Note also that `{T} = [v...]` would not quite work as intended because the method constructor does not yet know that `x` is to become an element of the new vector `v`. |
There was a problem hiding this comment.
Talking about {T} = [v..., x] like this does not make much sense. {T} is part of the method signature, not the body. As such, {T} = [v..., x] doesn’t have a meaning, it’s not even valid Julia syntax (you cannot assign a value to {T}).
There was a problem hiding this comment.
Yes, I realize that. And this is what made the whole {T} = ... difficult to process. Perhaps giving more examples would help. What would the syntax for a Tuplet be? (square brackets too?) When can the curly brackets around T be omitted? Please do make suggestions that could be used to improve the docs. Thanks.
There was a problem hiding this comment.
Maybe it’s easier to talk about it when using the long-form method syntax. The following are equivalent:
myappend(v::Vector{T}, x::T) where {T} = [v..., x]function myappend(v::Vector{T}, x::T) where {T}
return [v..., x]
endAs you can see, the second version has no {T} = ....
To return a Tuple instead of a Vector, you would use round brackets, i.e., return (v..., x). However, this has nothing to do with the parametric method syntax that is explained in this section. It is just the usual syntax to create Vectors and Tuples, respectively.
The curly brackets around T can be omitted here, they are only necessary when using several type parameters in the signature. For example, one could define a method myappend(v::Vector{T}, x::S) where {T,S}. Here, the curly brackets around T,S are necessary.
There was a problem hiding this comment.
Thanks sostock! I see I had totally misunderstood the function signature syntax. I thought the = [v...,x] part was part of the signature, but now I see that it's only the where {T} part.
Introducing the long-form method syntax first, and then saying that it could be written in an equivalent short-form, as you do, would have been clear. I'm not sure how many new users are likely to be confused by this. Perhaps more than one, because where {T} is pretty cryptic (I've got to re-read the docs to see if I understand it).
There was a problem hiding this comment.
Talking about
{T} = [v..., x]like this does not make much sense.{T}is part of the method signature, not the body. As such,{T} = [v..., x]doesn’t have a meaning, it’s not even valid Julia syntax (you cannot assign a value to{T}).
After seeing the long-form version, your comment now makes sense. I knew {T} was part of the method signature, but somehow I ended up thinking that the part after the equal sign was also a part of it. I was confused by the equal sign. I think it really helps to show the long-form and short-form side by side. The line break in the long form makes it clear where the signature ends, the equal sign not so much (to a newbie anyway). Thanks again for your help.
cleared up a confusion about where the function's signature ends
doc/src/manual/methods.md
Outdated
| ``` | ||
|
|
||
| The type parameter `T` in the function's signature ensures that the type of the new `v` is preserved after element `x` is appended to it. | ||
| The function's signature is preceded by the keyword `where` and is placed immediately after the method arguments. When only one type parameter is used, the curly braces are optional. An equivalent one-line definition is: |
There was a problem hiding this comment.
| The function's signature is preceded by the keyword `where` and is placed immediately after the method arguments. When only one type parameter is used, the curly braces are optional. An equivalent one-line definition is: | |
| The function's signature is preceded by the keyword `where` and is placed immediately after the method arguments. When only one type parameter is used, the curly braces are optional. An equivalent one-line definition would be: |
There was a problem hiding this comment.
I would just delete the part about the one-line definition. The two equivalent ways of defining methods are described at the top of the Functions section of the manual, I don’t see the point of repeating it here.
There was a problem hiding this comment.
sostock, you're right of course, but while I knew about the one-line style of definition I still got confused because my brain was focused on trying to understand the notation for types. And the section on Functions does not show types. I think it's useful to verbally explain the meaning of f(x::T) where T = T. The explanation could be moved a few lines down where this appears: mytypeof(x::T) where {T} = T.
There was a problem hiding this comment.
Maybe the one-line part could just be shortened, basically just saying something like “parametric method definition also works with the short-form syntax, which would look like this:”
There was a problem hiding this comment.
This is my first PR and I'm not entirely sure how I was to proceed. I went to the "commits" tab, edited, and committed again. I didn't want to overwrite the suggestions made by Simeon though. But do feel free to edit and put this matter to rest. Many thanks for your help!
grammar Co-authored-by: Simeon Schaub <[email protected]>
linebreaks Co-authored-by: Simeon Schaub <[email protected]>
incorporated comments by simeonschaub and sostock
correcting syntax Co-authored-by: Sebastian Stock <[email protected]>
Co-authored-by: Sebastian Stock <[email protected]>
Co-authored-by: Sebastian Stock <[email protected]>
|
Replaced by #51938 since upstream deleted their repo |
Closes #40650 Rebase of #40667 with edits, since upstream deleted their repo Co-authored-by: Patrick Toche <[email protected]>
As a newbie I struggled to understand the docs. I have added details that hopefully serve to clarify the issues. Please check that there are no misunderstandings on my part.
Closes #40650