Naming of XChannelEditSpec.Builder#addPermissionOverwrite is potentially confusing

[Laarryy]

Feature Description:

Modify the channel#addPermissionOverwrite method to internally fetch a list of all existing permission overwrites, add the one provided, and send the whole package to discord. This is opposed to current behaviour which is nearly the same as channel#addAllPermissionOverwrites except it only sends the one provided, deleting all others.

Justification:

At the moment, the textChannel#addPermissionOverwrite method will send an empty set with only the single specified permission overwrite to discord. By instead fetching all existing overwrites, adding the one provided, and sending the entire set, the method will be true to its name and will not delete all other existing overwrites. This will also make modifying channel permissions much simpler as the user would not have to get the list, create a new one with the added overwrite, and send them all manually.

[darichey]

To clarify: there is no TextChannel#addPermissionOverwrite. I believe you are looking at XChannelEditSpec.Builder#addPermissionOverwrite which, while maybe somewhat confusing, is working properly. The builder is building a new list of overwrites to send to Discord. You're adding to that list, but it doesn't contain all of the existing overwrites.

I don't think it would be wise (or even possible) to try to get that list to contain all of the existing overwrites by default. Instead, it would be nice if we had some kind of utility method that could signal to the request builder that the channel's existing overwrites should be included.

Unfortunately, the more I think about this, the more difficult it gets. This leads to a wider discussion about utility methods in specs (like button editing/disabling, to provide another example), potentially "polluting" the fields in the spec generator interfaces, and not painting ourselves into a corner for when we eventually want to try to move specs down to be usable in the rest module.

[Laarryy]

An alternative suggestion is always simply renaming the editspec's addPermissionOverwrite method to some name that communicates how addPermissionOverwrite will delete all other overwrites. overwritePermissionOverwrites is a funny name but probably not too wise. Nevertheless, a note in the javadocs about what that method actually does would be incredibly useful 😄