DIP16: Transparently substitute module with package

[Steven Schveighoffer]

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".

>> > 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.

-Steve