API reference improvements

[qwwdfsad]

It would be nice to systematically and extensively improve our API reference:

For every API endpoint, it would be nice to provide the following (example is the place where the property does not hold):

• Extensively document what the entity represents, whether it follows ISO-8601, how the entity can be acquired, and what time scale it comes from. Example
• Provide a minimum of how the entity can be used. Example
• Thoroughly explain the allowed and expected contract and behaviours and system-specifics. Example
• If applicable, provide contexts in which the entity is expected/recommended to be used (e.g. our README shines at that) and how it interacts with other (core) entities. Example
• Provide a basic usage example. Example
• If applicable, provide details about conversion rules, gotchas and recommendations. Example
• Where appropriate, information about conversions and interactions with native types (e.g. Instant <-> Java Instant conversion)
• Ensure that information used in our README is, in fact, deducible from the core entities documentation

[dkhalanskyjb]

If applicable, provide details about conversion rules, gotchas and recommendations. Example

I don't know of gotchas related to Instant. The only one that comes to mind is that instant + 1.days is a non-calendar operation (this could be worth documenting in the plus function), but I'd argue it's Duration's gotcha. Instant seems tough to use incorrectly to me. What gotchas did you have in mind?

Where appropriate, information about conversions and interactions with native types (e.g. Instant <-> Java Instant conversion)

When you have specific behavior on some platforms, you document it in the common code, makes sense; but when you have some extra interactions with platform code, you can't document them in common code (because symbols aren't resolved). If you have platform-specific documentation, in the IDE, it is either ignored (when writing common code) or replaces the common documentation. In the latter case, you have to repeat the common documentation for platforms and include platform-specific additions, which I think just isn't worth it.

If the system was a bit different and platform-specific documentation was added to the common documentation (and maybe the IDE would be smart enough to show the documentation for the platforms the project actually uses), then I agree that mentioning platform-specific converters and so on would be beneficial. Or better yet, if there was "extension documentation" along with extension functions: then we'd be able to show NSDate conversions in the Instant documentation for Darwin targets.