Missing method from API docs List.insertContentsOf

[icanzilb]

NB: Skip the original issue description and go directly to the first comment please: #3446 (comment)

Goals

List provides methods for inserting sequences of objects: 1) at the end of the list appendContentsOf and 2) to replace a range of existing objects replaceRange.

However there isn't a method to insert a sequence of objects at the beginning of the list (e.g. a method to correspond insert(_:atIndex:))

I would like to do something along the lines of (that throws an exception thought):

objects.replaceRange(0...0, with: newObjects)

But the method name does not really reflect what I want to do (i.e. I don't want to replace existing objects but to only insert new objects)

I would propose to add insertContentsOf() to have the methods consistent for inserting and appending.

Discussion: I would much rather have one method for adding a single object and a sequence of objects - it looks more swifty and I think will be simpler to use (even though it'll be a breaking change). Modifying insert and append to take as a parameter either T or [T] seems straightforward

Expected Results

objects.insertContentsOf(newObjects)

to insert a sequence of objects at the beginning of the list

[icanzilb]

It looks like the requested method insertContentsOf existing - it's just not showing up in the class docs here https://realm.io/docs/swift/latest/api/Classes/List.html:

[jpsim]

insertContentsOf(_:at:) (swiftdoc.org link) is declared on RangeReplaceableCollectionType, which List conforms to. This protocol provides a default implementation and overriding the default implementation wouldn't give us better performance.

So the limitation here is jazzy's, which we use for documentation generation. The oldest open issue in jazzy (realm/jazzy#8) is to display the inheritance graph in the rendered docs. I believe this is the right way to address this.

An alternative solution would be to add all inherited declarations as documentation members.

Since there's already an open issue in jazzy, let's close this one because the work can solely be done there.