Suggestion for documenting defdelegate

[pragdave]

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"

​

[Andrea Leopardi]

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

--
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 elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/d94f489a-74cc-4f79-9c77-d13a06d68123%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Andrea Leopardi

an.le...@gmail.com

[José Valim]

Hi Dave!

I actually agree with the principle. We tried copying the docs in recent versions for all defdelegate but it turned out that the documentation may refer to different variable names in the docs or link to local functions and types that do not exist in the delegator, that’s why we settled on simply linking to the delegated.

Btw, “see” could be implemented as a library today, it just needs to be a macro (a module attribute would be weird, especially since “@attr val” is meant to set the attribute, and not execute custom code). So I would go this route!

Thanks for the proposal!

--

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

[Andrea Leopardi]

Forgot to say, I think the best route would be @doc see: "String.length/1". Then it's the job of the doc tool to render it if they want to.

--

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 elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4KT55uQMFn6t6xGFed%2BgSHFL%2BYUJ7BhieAx_ov_B5FJ4Q%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Andrea Leopardi

an.le...@gmail.com

[pragdave]

On Friday, May 24, 2019 at 4:18:39 PM UTC-5, Andrea Leopardi wrote:

Forgot to say, I think the best route would be @doc see: "String.length/1". Then it's the job of the doc tool to render it if they want to.

But the _all_ doc tools would hav e to support it.... 

[José Valim]

Andrea, to clarify, @see would copy the docs. We could have a cross reference support, something like “@doc see: Foo” but that’s an annotation and I don’t believe it is what Dave is proposing.

Also, I personally like the README.md trick. I learned it from Dave and I use it in some projects. But I am perfectly fine with using File.read! To read it today. :)

[Michał Muskała]

At least on master, there is a delegate_to doc metadata key generated when using defdelegate. Without adding any documentation to the defdelegate function, the default documentation in IEx will include a short information "delegate_to: Bar.bar/0". It also seems this is consumed by latest ex_doc and generates a short default documentation of "See Bar.bar/0." with a nice link. So I think what you propose is what's already happening for the most part - there might be some edges to polish, but the large part of the functionality is here already.

Michał.

--

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 elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/d94f489a-74cc-4f79-9c77-d13a06d68123%40googlegroups.com.

[pragdave]

Btw, “see” could be implemented as a library today, it just needs to be a macro (a module attribute would be weird, especially since “@attr val” is meant to set the attribute, and not execute custom code). So I would go this route!

It definitely could, but then we'd need `use see` everywhere.

Is there any chance at all that we could have an `autorequire` attribute in mix.exs, So, it it had:

~~~ elixir

autorequire: [ Logger, See ]

~~~

and some module referenced `Logger` or `See`, then a require would be done automatically?

[José Valim]

I think an “import See” at the top of the modules delegating would be enough. Those modules are likely clean anyway, since they are a facade, and bringing the related functionality is better than relying on globals that affect the codebase as a whole. The fact require/import/alias are lexical is really important for keeping the code sanity and I wouldn’t want to change that.

[Andrea Leopardi]

Michal, TIL. Awesome, I'm looking forward to using this. No idea how I missed it, I suspect I just removed it from my memory lol

Andrea Leopardi

an.le...@gmail.com

--

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 elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/CAGnRm4%2BFN%3D8Go5KQkXpT6BXja7sOdDz%3D4%3DED6eexNFc6wA%3D-MQ%40mail.gmail.com.

[Rich Morin]

I don't have strong feelings about how this issue is resolved, but I'm very
interested in having some sort of tidy resolution. FWIW, I posted a note about
this topic to ElixirForum back in February:

Not sure how to document defdelegate entries
https://elixirforum.com/t/not-sure-how-to-document-defdelegate-entries/20502

I also note that belaustegui commented on this about the same time:

Defdelegate does not allow access to docs
https://elixirforum.com/t/defdelegate-does-not-allow-access-to-docs/12688

Dave's first suggestion (if a defdelegate does not have its own documentation,
could it receive a copy of the documentation of the function it delegates to)
would work fine for me, but I'm slightly concerned about backward compatibility.
In some existing cases, an implementation @doc entry might not be appropriate
for use with a defdelegate.

The @see syntax doesn't have this problem. It's also more explicit and it allows
more flexibility for what documentation gets used. So, I think I'd lean that way.

-r

[Steve Morin]

@see seems like a very elegant solution.

--
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 elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/72452964-30EB-48B6-B11C-3384F4B6EFBB%40gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Steve Morin | Hacker, Entrepreneur, Startup Advisor 

twitter.com/SteveMorin | stevemorin.com

Live the dream start a startup. Make the world ... a better place.