Uniting library traits

Jonathan M Davis newsgroup.d at jmdavisprog.com
Wed Nov 14 22:19:17 UTC 2018


On Wednesday, November 14, 2018 7:54:12 AM MST Jesse Phillips via 
Digitalmars-d wrote:
> > So, if it turns out that a particular trait is needed by
> > druntime, it does make some sense to move its implementation to
> > druntime, and then have std.traits publicly import it, but from
> > the public API perspective, it should still be in Phobos, and I
> > don't think that we should be trying to move all of the traits
> > into druntime - just those few that we find that are actually
> > needed there.
> >
> > - Jonathan M Davis
>
> What about the docs? Should doc generation merge in public import
> docs? Seem generally useful.

The documentation should just go in Phobos in this case, since the traits
aren't intended to be part of druntime's public API. They're in
core.internal.

As for copying documentation with a public import in general, I'm inclined
to argue that it's better to just point to the original documentation. Links
in the documentation could easily have been written to be local to the
module that they were in, breaking them if the documentation is copied.
Similarly, the description could become confusing if it assumes that it's in
a particular module when it isn't. Linking to the original description puts
you in the correct context when reading the it, whereas copying it does not.

Another interesting quirk of description that I hadn't thought of that was
taken into account with the recent PR to consolidate the implementation of
Unqual was that the description talked about T, and while Unqual has T when
defined as a template, a public import would not. So,
core.internal.traits.Unqual was privately imported as a renamed import of
CoreUnqual and then wrapped with a thin template named Unqual which simply
instantiated CoreUnqual just so that the declaration in the documentation
would have T in it, and the documentation would make sense when talking
about T, which it wouldn't have if it had been a public import or alias.

- Jonathan M Davis





More information about the Digitalmars-d mailing list