You're right that we have no guideline but the following is the guideline that
we should have:
# Forward declarations that describe the interface
proc featureA*() {.tags: <explicit list>, raises: <explicit list>, gcsafe
etc.}
## Documentation
proc featureB*() {.tags: <explicit list>, raises: <explicit list>, gcsafe
etc.}
## Documentation
when defined(posix):
include impl_posix
elif defined(windows):
include impl_windows
else:
include impl_fallback
Run
Advantages:
* Documentation is kept in a single place.
* The implementation is checked statically against the interface declarations.
* Shields us from effect inference differences between the different
implementations.
Disadvantages:
* Explicit effects are verbose and annoying. But that's just the price of
having effects in the language, I suppose.
