chpldoc should document transitive (public) uses

[bradcray]

As a Chapel programmer, it'd be helpful if a module's chpldoc-generated page showed the public use clauses contained at module-scope so that I'm aware what symbols beyond the module itself I'm gaining access to. Ideally, this would be hyperlinked to the module / symbols in question.

For example, given:

module C_Lib {
  proc c_fn() { ... }
}

module Lib {
  proc fn() { c_fn(); }
}

If Lib...

• contained public use C_Lib, it'd be nice to see that in its docs and have C_Lib link to the chpldoc page for module C_Lib
• contained public use C_Lib only/except c_fn;, it'd be nice to see that in its docs, with C_Lib linking to module C_Lib's chpldoc page and c_fn linking to the entry for c_fn()
• if public use C_Lib ...; appeared within fn() itself, chpldoc shouldn't show anything (since it's local and therefore doesn't impact what I see.

[and ditto for import]

[bradcray]

I think a way to get 90% to a solution on this issue is to rewrite:

public use Foo;

into:

.. include:: Foo.rst

in the sphinx rst file. The other 10% is to make sure that the formatting is appropriate in terms of standard header/footer stuff in Foo.rst.

[mppf]

@arezaii - is this still an issue? I thought we had a flag that was working to do this.

[arezaii]

chpldoc has had, and continues to support, the process-used-modules flag. I'm not sure if it meets all the needs expressed in the desired behavior though. There are some examples of it in action in test/chpldoc/multifile, test/chpldoc/include/, and test/chpldoc/module/publicUseIOTest, but not sure it behaves exactly as desired above.

[lydia-duncan]

My understanding was that Process Used Modules was about whether the used modules would get a page documenting them present in the first place. If I remember right, it's used to avoid building library documentation (like IO, Math, etc) when chpldoc is called for user code and to ensure we include it when we build the documentation we host ourselves

[lydia-duncan]

This, on the other hand, is about how the documentation of a particular module responds to the fact that it has a public use/import in it - to be more helpful to clients of that library by having the documentation behave like using the module itself in terms of enabling you to look up symbols that act like they are defined in it

[mppf]

OK, I'll try to summarize/clarify.

If I have

Lib.chpl

module Lib {
  public use C_Lib;
  proc fn() { c_fn(); }
}

C_Lib.chpl

module C_Lib {
  proc c_fn() { }
}

Then running

chpldoc Lib.chpl  --text-only --process-used-modules

produces

docs/Lib.txt

Lib

Usage:
   use Lib;

or

   import Lib;

   proc fn()

docs/C_Lib.txt

C_Lib

Usage:
   use C_Lib;

or

   import C_Lib;

   proc c_fn()

(where the C_Lib.txt is created only if we pass --process-used-modules).

This issue is requesting that the documentation for Lib.txt include some sort of acknowledgment that C_Lib and/or c_fn are public and available.

[bradcray]

It could also simply "inline" the documentation for C_Lib into the documentation for Lib as proposed in https://github.com/chapel-lang/chapel/issues/14601#issuecomment-1036798841. However, this wouldn't be so simple if only a subset of C_Lib were re-exported.

[lydia-duncan]

Note that #25633 is related to this issue and should be considered when resolving it - removing symbols that are re-exported should probably be considered a breaking change, and will definitely need to be considered that way when re-exported symbols are included in the documentation of a module