Submodules: access of objects and documentation of modules

General Usage
,
1

Let’s say I have a package with the following organisation (from @GunnarFarneback on post:2 of topic:21709):

P.jl:

module P
include("C.jl")   # shared utilities code
include("M1.jl")
include("M2.jl")
end

M1.jl:

module M1
using ..C
end

M2.jl:

module M2
using ..C
end

C.jl:

module C
end

How do I access objects in M1/M2/C from:

  • the same module
  • the “sister” modulesmodule
  • the test script
  • the outer world

I have no clear what I have to export, if I have to export only once in the submodule or I have also to reexport it in the main module, and if some functionality in the utility module C is only for the sister submodules if I still need to export them.

Also, is there a way to document a module with a docstring in the same way we do for a function ? How users then retrieve such documentation ?

1 Like
2

Here is an example illustrating (I think) all cases:

"""
A docstring for P
"""
module P

module C
  # the function we're interested in
  foo() = 42

  ## optionally, if you want to export foo:
  # export foo

  # use from inside the submodule itself
  barC() = foo()
end

module M1
  # from a sibling, using a relative path
  using ..C
  bar1() = C.foo()  # or just foo() if it was exported
end

module M2
  # since P is in your case the top-level module of a package,
  # an absolute module path also works
  using P.C
  bar2() = C.foo() # or just foo() if it was exported
end

# use from the parent
barP() = C.foo()

## or, if foo was exported:
# using .C
# barP() = foo()

end

From outside the package (which includes other packages depending on P, the REPL when P is the active environment, or runtests.jl):

julia> using P
julia> P.C.foo()
42

In the REPL, docstrings for modules can be retrieved in the usual way:

help?> P
search: P Ptr pi pwd Pipe Pair put! prod pop! push! prod! print parse pairs pkgdir pathof parent promote println prevpow prevind pointer prepend! powermod position

  A docstring for P

  ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

  A docstring for P
3 Likes