DIP16: Transparently substitute module with package

[Jonathan M Davis]

On Friday, April 06, 2012 07:56:41 Steven Schveighoffer wrote:
> On Thu, 05 Apr 2012 19:14:42 -0400, Jonathan M Davis <jmdavisProg at gmx.com>
> 
> wrote:
> > On Thursday, April 05, 2012 17:33:50 Steven Schveighoffer wrote:
> >> Why do we ever need to split modules for documentation? Just fix the doc
> >> generator so it's not as monolithic. For instance, have one page per
> >> class or struct.
> > 
> > That may or may not be desirable (certainly in the case of smaller
> > types, I'd
> > argue that it isn't). By doing it on a module basis, you have far more
> > control. But regardless, that would be a major change to ddoc.
> 
> ddoc's output leaves a lot to be desired.  The unorganized links at the
> top suck.  Using module order to show symbols instead of category of
> symbols.
> 
> How is a doc page ever "too big"?  Even std.datetime loads in a second.
> It's more that it's "too disorganized".

There's no question that the links at the top suck, and std.datetime is the 
poster child for why they suck. The page is too large for how its organized, 
and it _does_ take significantly longer to load than other Phobos pages, even 
if it's still usable. There's no question that better links would help 
significantly though.

Regardless, there's enough content there that it would arguably be better 
served if it were multiple pages.

> >> > And if all you care
> >> > about is sub-modules for implementation and want all of the functions
> >> 
> >> in
> >> 
> >> > the
> >> > same module still, then this DIP is pointless. All you have to do is
> >> > declare
> >> > undocumented sub-modules which hold the various implementations and
> >> 
> >> have
> >> 
> >> > the
> >> > actual module call them. We already do this sort of thing in Phobos to
> >> > get
> >> > around static destructors screaming about circular dependencies.
> >> 
> >> You are starting to see my point :) But I think the issue is not so much
> >> that you are splitting the implementation, but splitting up the API into
> >> related modules.
> > 
> > As I understand it, the entire point of this DIP is to enable splitting
> > up the
> > API cleanly without breaking code. The implementation can already be
> > split up
> > seemlessly.
> 
> As can the API via public imports.

Not and keep stuff in the same place in the hierarchy. You have to create a 
completely separate package. The point of the DIP was to make it so that you 
could do it _in place_ by turning a module like std/algorithm.d into the 
package std/algorithm/ with modules inside it.

Right now, I can go and split up std.datetime into a new package (e.g. 
std.dtime) and then publicly import it all from std.datetime, but then the new 
package is completely separate from the module which imports everything. It 
also makes it look like std.datetime should go away in favor of just keeping 
std.dtime (the same with std.algorithm if it gets split), which may or may not 
actually be desirable. Organizationally, it would be much nicer to be able to 
turn std/datetime.d into std/datetime/, and _that_ is what the DIP is trying 
to enable. The rest can be done now but not that. You can't split up the API 
in place.

- Jonathan M Davis