doc-only imports

[CeylonMigrationBot]

[@lucaswerkmeister] I propose to add documentation-only imports, which ceylondoc can use to resolve doclinks to modules not otherwise imported.

Consider, for example, the following modules:

"Bla bla.
 Commonly used in conjunction with [[module ceylon.ast.redhat]].
 After conversion using that module,
 you may feed this into [[module ceylon.formatter]]."
module ceylon.ast.core "1.2.0" {}

"Processes ASTs from [[module ceylon.ast.core]]."
module ceylon.ast.redhat "1.2.0" {
    shared import ceylon.ast.core "1.2.0";
}

Only one of these three doclinks will work – and it’s impossible to make the other two work, since that would require circular dependencies between modules, and a dependency of ceylon.ast.core onto a module which it shouldn’t depend on (ceylon.formatter).

To solve this, I suggest the following syntax:

"…"
module ceylon.ast.core "1.2.0" {
    doc import ceylon.ast.redhat "1.2.0";
    doc import ceylon.formatter "1.2.0";
}

These doc imports serve only to inform ceylondoc that these modules will be available, and that links to them should be allowed (with correct output). They do not introduce a module dependency, and are not available at runtime.

(Sorry if this isn’t the correct repo, but I don’t think this belongs in .language or -compiler.)

[Migrated from ceylon/ceylon-spec#1462]

[CeylonMigrationBot]

[@thradec] I think that this requirement doesn't happen much often and can be workaround by direct link into herd. So I wouldn't add something special just for it.

[CeylonMigrationBot]

[@gavinking] This looks reasonable to me. We have needed it in a couple of places.

[CeylonMigrationBot]

[@Zambonifofex] Sorry, but is there any reason that you can't allow reference to modules that are not imported? Can't you just look at the module in the link and assume the doc import? Maybe it's more useful when referencing members of the modules?