@moduledoc metadata

[LostKobrakai]

This might actually be a bit more difficult than expected.

It seems simple to add moduledoc metadata to all the modules having a use Boundary, but what about the modules implicitly bound to that boundary.

And the other factor is: Do we at this point actually already know the relevant data about the boundary so it can be set as metadata? For the boundary roots – maybe. For modules implicitly part of a boundary – unlikely.

[sasa1977]

Yeah, I originally thought that we'll add metadata only to the root module. We can't do anything for other boundary members, because their state is known only after the entire project is compiled, and so we end up with a chicken & egg situation where we want to inject some data into the module's beam file, but to get that data the module needs to be compiled first. Ultimately, boundary's complete state can only be determined after the app is compiled, so we're limited in what can we inject in a single module while the project is being compiled.

So I think that the best we can do for meta is to generate something like boundary: boundary_info in the root module, where boundary_info could be the opts which are passed to use Boundary. For richer boundary support tools such as ex_doc would need to either work directly with boundary, or otherwise provide some hook which is invoked after the project is compiled but before the output (like e.g. docs) are generated.

[LostKobrakai]

Yeah, I'm wondering if adding documentation metadata is actually a useful thing to do then. Because the real usefulness comes out of knowing what belongs together and if a current module might be exported or not; less so from knowing something is a root module. I still feel my other proposed change is useful though.

[sasa1977]

Yeah, I'm wondering if adding documentation metadata is actually a useful thing to do then. Because the real usefulness comes out of knowing what belongs together and if a current module might be exported or not; less so from knowing something is a root module. I still feel my other proposed change is useful though.

I originally thought that meta might be useful to present some additional info in docs, like what does some boundary export and what it depends on. I agree that this is not a lot, given that this meta is available only in the boundary's root module, which means that if I invoke an inner module, like Foo.Bar.Baz, I have to know to which boundary it corresponds to.

[LostKobrakai]

which means that if I invoke an inner module, like Foo.Bar.Baz, I have to know to which boundary it corresponds to.

That's exactly my problem with it. I'd actually prefer to look into a more first party integration with ex_docs for boundary, as adding metadata to only the root modules wouldn't actually solve my goal in this: Going to a module in the docs and getting to know: Which boundary does it belong to? Which modules are allowed to call the functions documented on the same page? If it's a root module: Which modules are exported? Which modules belong to the current boundary? …

[LostKobrakai]

I'll close this for now, but might revisit this at a later time.