DIP16: Transparently substitute module with package

[Jonathan M Davis]

On Thursday, April 05, 2012 17:33:50 Steven Schveighoffer wrote:
> On Thu, 05 Apr 2012 17:02:13 -0400, Jonathan M Davis <jmdavisProg at gmx.com>
> > If the module isn't large enough to be split for documentation, I find
> > it hard
> > to believe that it needs to be split for maintenance.
> 
> 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.

In either case, the size of the documentation page for a module is currently 
closely tied to the number of public symbols in the module, so if you have a 
large API, it can become desirable to split it up simply because the 
documentation page for it is too large. And by splitting up the API, you fix 
that problem. Not to mention, if the module is mostly free functions, putting 
the documentation for each class or struct on its own page doesn't help 
anyway. So, while that may be a good change to ddoc in at least some cases, it 
doesn't solve the problem in general. For instance, it would help 
std.datetime, but it wouldn't help std.algorithm at all.

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

- Jonathan M Davis