Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Better documentation for `methods` #34761

Open
Nosferican opened this issue Feb 14, 2020 · 10 comments
Open

Better documentation for `methods` #34761

Nosferican opened this issue Feb 14, 2020 · 10 comments

Comments

@Nosferican
Copy link
Contributor

@Nosferican Nosferican commented Feb 14, 2020

I believe methods should have a bit more of information, consider,

struct A end
methods(A)
struct B{T} end
methods(B)
methods(B{Int})
struct C{T}
    C(x) = new{Int}(0)
end
methods(C)

Basically the way that methods are collected / match isn’t well documented.

@KristofferC

This comment has been minimized.

Copy link
Contributor

@KristofferC KristofferC commented Feb 14, 2020

What is the surprise here? A you can just create with A() so A has one type constructor. For B you need to create it as B() since cannot determine T so you have no methods for B. But you can do B{Int}() so B{Int} has one method. For C you have an explicit inner constructor which makes C(x) available so C has one method.

What is the documentation you are missing?

@Nosferican

This comment has been minimized.

Copy link
Contributor Author

@Nosferican Nosferican commented Feb 14, 2020

That explanation? Basically methods should have some basic comments on how it looks up / determines which methods to list. Something like, for parametric types it would only list methods for which it can determine the types or such.

@yuyichao

This comment has been minimized.

Copy link
Contributor

@yuyichao yuyichao commented Feb 14, 2020

No but that has nothing to do with methods, which only care about the function/value you pass to it and not about any derived objects from it.

@yuyichao

This comment has been minimized.

Copy link
Contributor

@yuyichao yuyichao commented Feb 14, 2020

And this is document where it should be: the constructors for parametric types https://docs.julialang.org/en/v1/manual/types/#Parametric-Types-1

@Nosferican

This comment has been minimized.

Copy link
Contributor Author

@Nosferican Nosferican commented Feb 14, 2020

The parametric types subsection in the Methods section would be a nice place. Maybe have an example for specifying that for methods for parametric types, one has to pass the non-determined types to list those methods as those are determined by the arguments to the constructor including the parametric types.

@yuyichao

This comment has been minimized.

Copy link
Contributor

@yuyichao yuyichao commented Feb 14, 2020

one has to pass the non-determined types to list those methods as those are determined by the arguments to the constructor including the parametric types.

No there's no such rule like that and this is NOT about parametric method, it's about constructors of parametric types which aren't necessarily parametric methods. The rule is that if the method exist it'll be returned and if it doesn't exist it won't be. What you are descrirbing is he rule of adding default constructor, and that's why it's documented exactly as that in the parametric type section. Starting from

How does one construct a Point object?

@yuyichao

This comment has been minimized.

Copy link
Contributor

@yuyichao yuyichao commented Feb 14, 2020

Basically the way that methods are collected / match isn’t well documented.

And I agree it could be nice to add a link to the method page and maybe a clarification that it corresponds to what you get when you call the exact object you passed in. These are "the way that methods are collected / match".

However, what you are confused by isn't this rule, it's the rule for default constructor. That rule, along with many other things like the available constructor for base types, base methods, default/keyword arguments, how to add methods, etc are rules about what methods actually exists and those does not fit here.

@Nosferican

This comment has been minimized.

Copy link
Contributor Author

@Nosferican Nosferican commented Feb 14, 2020

Having a default constructor or not is not the issue. The default constructors rules are pretty straightforward.

struct A{T} end
struct B{T}
    B{T}() where T = new{T}()
end
struct C{T}
    C{T}() where T = new{T}()
    C(x::T) where T = new{T}()
end
struct D{T}
    x::T
end
methods(A)
methods(A{Any})
methods(B)
methods(B{Any})
methods(C)
methods(C{Any})
methods(D)
methods(D{Any})

What I and others thought was that the parametric type declarations were treated as arguments (A{<:Any}) rather than part of the method identifier. It took us a minute to realize what was going on but would have been nice to have had some guidance in the docstring.

Guess it could be either in the manual or in the docstring as examples.

@yuyichao

This comment has been minimized.

Copy link
Contributor

@yuyichao yuyichao commented Feb 14, 2020

What I and others thought was that the parametric type declarations were treated as arguments (A{<:Any}) rather than part of the method identifier. It took us a minute to realize what was going on but would have been nice to have had some guidance in the docstring.

Well, but at least according to the first post you didn't have a correct interpretation of what's happening. A and A{Any} are completely different objects. If you expect methods(A) to return anything, you should also expect A(...) to work for some arguments. If you know exactly how default constructors work, you should not expect A(...) to work and that's exactly why methods(A) returned an empty list.

This will be a bad example to give in the method section because it leads people to believe there's something special about constructor methods, there's none. You can certainly ammend the default constructor section to include methods call in additional to calling the constructor directly and obsereve the result/error.


Also:

The default constructors rules are pretty straightforward.

That rule is exactly

Something like, for parametric types it would only list methods for which it can determine the types or such.

@yuyichao

This comment has been minimized.

Copy link
Contributor

@yuyichao yuyichao commented Feb 14, 2020

If you expect methods(A) to return anything, you should also expect A(...) to work for some arguments.

And I'm not implying that the document is super clear about this, which is exactly what I think the document should be improved on #34761 (comment). I acknowledge you have some confusion, but the confusion should be fixed in the doc by adding the correct explaination (what methods is actually doing) rather than adding some special case where there's nothing special about as far as methods is concerned (constructors).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.