Making `setindex` public, how to document it, rethinking the Collections docs

nsajko
Wed, 24 Jul 2024 14:15:48 +0000
Internals & Design

@aplavin is trying to make Base.setindex a public API of Julia, which seems like a good idea, given that many packages use it already and it seems like an OK interface. The question is, how to document it. The function is a collection interface, many (immutable) collections in the ecosystem implement it already.

The signature is basically setindex(collection, new_value, index_of_the_value_to_be_replaced). Given that it takes an index into collection, it seems like it should go into the Indexable Collections section of the “Collections and Data Structures” page. However it also doesn’t fit there because the collections listed as fully implementing the “indexable collection” interface don’t implement setindex.

Thus I believe we may need to restructure the docs page somewhat: Collections and Data Structures · The Julia Language

This is @aplavin’s PR:

github.com/JuliaLang/julia

make Base.setindex() public

JuliaLang:master ← aplavin:patch-14

opened 05:31PM - 15 Jul 24 UTC

aplavin

+2 -0

setindex() is a widely used well-documented function, it should be marked public…, right? Not sure what's the right way to make a function with multiple methods public, please correct me if I'm wrong here!

This is a related issue on Julia’s Github:

github.com/JuliaLang/julia

Taking collection interfaces seriously

opened 10:50PM - 02 Jan 24 UTC

CameronBieganek

domain:docs domain:collections

This will probably get closed as a duplicate, but I think it is high time that w…e provide actual interface definitions for the various collection categories listed on the ["Collections and Data Structures"](https://docs.julialang.org/en/v1/base/collections/) page of the manual. That page hints at interfaces for the various categories, but does not provide a clear guide to which methods are required and which methods are optional in order to implement the various interfaces. (Plus, that page includes docstrings for a bunch of functions that most likely do *not* need to be implemented by new types.) Here is a list of collection interfaces from that page that need better documentation on the interface requirements: - [ ] General Collections - [ ] Indexable Collections - [ ] Dictionaries (`AbstractDict`) - [ ] Set-Like Collections (`AbstractSet`) - [ ] Dequeues See also #34677 and #25941. And also #28784 for documentation of the `AbstractString` interface.

Pinging people from that issue: @CameronBieganek @Raf @ToucheSir @Sukera @jakobjpeters, hoping you can provide input on how to restructure the docs page.

14 posts - 5 participants