Apple has a principle of progressive disclosure that is core to their SwiftUI API. They took the time to explain it in detail at WWDC '22 - The Craft of SwiftUI API Design. A key point is that Apple wants to optimize for the Call Site, not the programmer's typical view of the Declaration Site. Let that sink in a bit... it is a powerful choice. Sam does a wonderful job of explaining the principle of Progressive Disclosure as it applies to the API design. His examples are very illustrative.

However, here is the GAP - the beginner programmer is not served by the API's progressive disclosure. That disclosure of more and more detail is only presented through the interaction of the user interface (UI). It makes the development more difficult to learn. The programmer may wish to do more complex behaviors but it is not at all clear how to implement those undiscovered behaviors.

As an example consider the typical Swift Charts example. And then try to add custom axis labels. It is not at all clear how that default axis label gets determined nor how to augment the axis labeling.

The only resolution to this gap that I can find is excellent documentation. Writing that goes far beyond explaining the call site parameters... far beyond explaining the behavior of the methods and classes. Writing that imagines the programmer who wants to not only use the simplest use case but extend their code to use the full extent of the API.

Here is an example of great documentation by Big Mountain Studio Charts - for iOS 16 SwiftUI View Mastery.