[Issue 20462] New: [SPEC] Clearly document rules of package attribute on module.d vs. package.d file names

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=20462

          Issue ID: 20462
           Summary: [SPEC] Clearly document rules of package attribute on
                    module.d vs. package.d file names
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dlang.org
          Assignee: nobody at puremagic.com
          Reporter: ibuclaw at gdcproject.org

Notably be more explicit in the spec that as soon as you convert a module into
a package.d source, then *that* now becomes the innermost package.

i.e:

---
// (std/internal.a.d): package = stdx
module stdx.internal.a;
import stdx.b;

void main()
{
    foo();
}
---

---
// (stdx/b.d): package = stdx
// (stdx/b/package.d): package = stdx.b
module stdx.b;

package void foo()
{
}
---

In one directory structure, 'foo' is visible from stdx.internal.a, in another,
'foo' becomes undefined, and so you will need to explicitly say which package
you want it to be visible from in order to compile.

---
// (stdx/b/package.d): package = stdx.b
module stdx.b;

package(stdx) void foo()
{
}
---

--