I'm not sure I like the motivation with defdelegate, but I'm interested in the @see module attribute. Maybe it should take a string containing an ExDoc-friendly link though. For example, "String" would point to the moduledoc of String, "String.length/1" of that function, "t:String.t/0" for that type, and so on. I'm not sure about the pages though, I don't like reading the contents of the file since it feels against the current API.
Andrea On Fri, 24 May 2019 at 22:34, pragdave <[email protected]> wrote: > I quite often put the API for a library in the top-level module, but > delegate all the calls down into various implementation modules. > > This leaves we with the problem of where to put the @doc. > > I want to put it in the API module so that clients of the library can see > all the API documentation by asking for help on the functions they actually > call. > > I also want to put it in the implementation modules so that people reading > the code have access to it. > > So, my suggestion: if a defdelegate does not have its own documentation, > could it receive a copy of the documentation of the function it delegates > to? This means the source could have just one copy (in the implementation), > but iex, hexdocs etc would also see it at the top level. > > This would be my preferred change. However, if it isn’t acceptable, I have > a plan B. > > Could we have an @see directive which could be used with @doc and > @moduledoc? > > @doc @see Mylib.Stats.stddev > defdelegate stddev(sample), to: Mylib.Stats > > If @see is passed a module, it returns the moduledoc. If passed a > function name, it returns the docstring. If passed a string, it returns the > contents of the given file. Whaa??? you say. Doing this means we can > document the top-level using > > @moduledoc @see "README.md" > > > > -- > 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/d94f489a-74cc-4f79-9c77-d13a06d68123%40googlegroups.com > <https://groups.google.com/d/msgid/elixir-lang-core/d94f489a-74cc-4f79-9c77-d13a06d68123%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > -- Andrea Leopardi [email protected] -- 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/CAM9Rf%2BKpp0OEerk_oOig%2BmO%2Bu764YFfFFK1C9fD-VDzebhNFzg%40mail.gmail.com. For more options, visit https://groups.google.com/d/optout.
