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

the GenericMemory doc string isn't included in the docs #53854

Open
nsajko opened this issue Mar 26, 2024 · 4 comments · May be fixed by #54642
Open

the GenericMemory doc string isn't included in the docs #53854

nsajko opened this issue Mar 26, 2024 · 4 comments · May be fixed by #54642
Labels
design Design of APIs or of the language itself domain:docs This change adds or pertains to documentation

Comments

@nsajko
Copy link
Contributor

nsajko commented Mar 26, 2024

GenericMemory is referred to in three places in the in-development docs, but not documented itself. It's public and has a doc string, though, although the doc string doesn't describe the kind and addrspace type parameters.

@nsajko nsajko added the domain:docs This change adds or pertains to documentation label Mar 26, 2024
@nsajko
Copy link
Contributor Author

nsajko commented Mar 26, 2024

GenericMemoryRef is likewise public and not documented, but it doesn't have a doc string, either.

@oscardssmith
Copy link
Member

I think this was somewhat intentional. We know that regular Memory has the interface we want, but I think we wanted a release or two and a few examples using the addrspace and kind before we actually decide that the GenericMemory doesn't have any design defects that would require breaking changes if it was part of the interface.

@nsajko nsajko added the design Design of APIs or of the language itself label Mar 27, 2024
@nsajko
Copy link
Contributor Author

nsajko commented Mar 27, 2024

If GenericMemory or GenericMemoryRef aren't part of Julia's API, probably they:

  1. shouldn't be public/exported (currently we have Base.ispublic(Core, :GenericMemory) == Base.ispublic(Core, :GenericMemoryRef) == true and they're exported into Main)

  2. shouldn't be referred to from anywhere in the documentation

@LilithHafner
Copy link
Member

@oscardssmith, would you be willing to put a note in the docstring describing what is and isn't guaranteed to remain stable?

e.g. should package authors define f(::Memory{T}) where T or f(::GenericMemory{IDK, T}) where {IDK, T}. Lacking this I think it's all going to end up semi-public upon the release of 1.11 at the very least.

@KristofferC KristofferC removed this from the 1.11 milestone May 8, 2024
@oscardssmith oscardssmith linked a pull request May 31, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
design Design of APIs or of the language itself domain:docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants