These are really good examples, all the ideas about ExDoc are great. I also agree with the point about warnings. It might be actually even better then throwing a compilation error (at least for now). Having compiler throw warnings in this case would make it much easier to enforce boundaries (because we already have a way to treat warnings as errors) while keeping the compatibility with Erlang. I think it would be a reasonable step forward.
W dniu wtorek, 12 grudnia 2017 12:51:50 UTC+1 użytkownik W-M Code napisał: > > I also commonly come across modules that are listed in ExDoc but turn out > to only be part of the implementation of the 'main' module of the library, > as well as the inverse, where I am myself creating a library and I'd want > to split stuff up in multiple modules but end up not doing it because I > don't want to confuse the user of the library with the extra modules. > > More importantly than the second point though, is the fact that I actually > *do* want to have documentation (including possibly doctests) for my > 'private' modules' public functions (So functions that are used by other > modules in my library). This to: > > 1. Inform my future self and other contributors to the open source project > about design choices made in the implementation of certain functions. > 2. Sometimes, test these functions. (There is some arguing about this; > some people say that testing should only occur at the most external layer > of your library, but I concur because often, libraries end up being nested > (without it making sense to split stuff into multiple physical libraries)). > > I really would like to use the markdown-syntax for this, and also to > generate ExDoc pages that include this information (as well as showing it > within IEx). *Of course, with a disclaimer that this function is part of > a 'private' module and should not be used by consumers of the library but > only by the library itself.* > > @Christopher Keele's trick to still use Markdown-syntax is interesting, > but since it is not actually compiled to any documentation I don't think it > is particularly useful. > > Personally, I do think that having a way to annotate modules as protected > or private (Possibly, protected is the more accurate name for this > functionality?) that would: > - Generate disclaimers on top of documentation, possibly hiding the actual > documentation behind a 'spoiler'-like tag to make sure that people don't > glance over the disclaimer. > - Show references to the modules in a different color (i.e. 'faded out') > in ExDoc (and possibly IEx) to make sure that people see that these modules > are uninteresting for the outside world. > > This would already protect against 95% of the 'bad use'. In the end, if a > user wants to do something what is bad for them and we have informed them > that it is bad, it is their own choice, after all. > > And yes, maybe we could also have the compiler throw warnings when a user > does decide to depend on an 'internal' function. But I think that is all > that is needed. > > ~Wiebe-Marten Wijnja/Qqwy > > On Sunday, December 10, 2017 at 9:34:43 PM UTC+1, Maciej Kaszubowski wrote: >> >> Hello, >> >> *What?* >> >> I would like to propose introducing a possibility to make a module >> protected/private. Functions from such module would not be visible outside >> of the OTP application they are defined in. >> >> *Why?* >> >> Currently, all modules included in the release are globally visible. This >> makes it harder to enforce correct architectural boundaries because we have >> no support from the compiler. We can only enforce the boundaries by being >> careful or by running external scripts, but both solutions fall short when >> the developers are under pressure or before deadlines. >> >> It would be nice if it was possible to create a module which can only be >> accessed from the inside of a library/application where it's defined. We >> have private functions, so it would be nice if we could do the same for >> modules which are one abstraction level higher. This would allow to clearly >> define a public interface for libraries/applications which would result in >> better design. Since one of the recent Elixir goals is to help creating >> maintainable software, I think this feature would be a really good step in >> this direction. >> >> *Issues* >> >> Proposed behaviour could be problematic due to the fact that all Elixir >> modules compile to Erlang modules which are all public. I came up with >> three possible ways to handle this: >> >> 1. Compile all modules modules as usual (resulting in public Erlang >> modules), but have Elixir compiler fail when the function from >> private/protected module is called. >> 2. Don't create Erlang modules from private/protected Elixir modules and >> "copy" the functions to public modules that use them. >> 3. Treat all modules are public and use mix xref task to validate this >> behaviour outside of the compilation step. >> >> All of the solutions have advantages and disadvantages and maybe there >> are some others which I didn't think of. >> >> I'll be happy to know what you think about this. >> >> Cheers, >> Maciej >> > -- You received this message because you are subscribed to the Google Groups "elixir-lang-core" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/06c37228-9326-4833-9b75-af20ff0613d5%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
