New Feature: Copy documentation (Continuation of PR #2115)

[a-maze-d]

This is a continuation of the PR #2115 that can copy the documentation from another module/function and it rewrites the documentation so that the links are updated correctly

I have created a small test application to cover as many cases as possible for the rewriting of the documentation. Those cases made it then also into the unit tests, but it's potentially easier to see how the output looks

One thing that is not done is to add documentation (because I'm not sure where the best place would be). I'm happy to add this in another commit. but here are the highlights:

• add @doc copy: true to copy the documentation of a defdelegate to copy it's documentation

• add @doc copy: {m, f, a} to copy the documentation as specified by `{m, f, a}

• You can specify a new config parameter :copy_doc_decorator to decorate the documentation to your liking to indicate that the documentation was copied. The default will add at the end: "Note: documentation was copied from: #{m}#{f}/#{a}" If you provide your own decorator, then you have to provide a function that returns an updated doc (String). The function gets called with 2 arguments:

  • doc (String): the documentation with rewritten code snippets, so links point the correct direction
  • {m, f, a} (Tuple): This provides information from where the documentation was copied from

Note:
I have tested as many cases that I could think of, the code I added received unit tests (100% code coverage). I'm happy to fix anything I might have missed.

[a-maze-d]

the best spot for the documentation might be here, but it would be the Elixir documentation:

[josevalim]

Thank you. I believe you have not considered specs, right? All of the specs need to be rewritten too, including references to local calls which need to be expanded as remotes.

[a-maze-d]

That is correct. I reflected quite a bit on that and the reason for that is because I'm only copying the documentation, not the spec. The spec is treated separately and only added when writing the documentation.

IMHO, this could be another feature (or maybe integrated into this one as an extra option) in the future.

[a-maze-d]

Here the docs (first the original, second the delegate)

[josevalim]

Thank you. I think people will expect the spec to work too, so we would need to tackle that. Especially because the docs can refer to something defined in the spec.

I understand it is too much work though. On the other hand, I guess we will need to handle copying the types in Elixir’s future type system as part of the language, so the types should just work, but then I’d block this until we have support for Elixir new types.

[a-maze-d]

Fair enough, even thought the whole copying is opt-in, so it's up to the doc-writer to decide. And if you leave the note where it's coming from, you can always see what the type-spec is.

I can take a look on what it would take to take over the spec too.

[josevalim]

If we support this, we should use it for delegate, and those are all the expectations people had in the past. Although it probably doesn’t make sense to put all of this effort into typespecs, given we will likely have an alternative in 1y. So I would probably just wait and revisit it later :(

[a-maze-d]

OK. Feel free to ping me if you want me to look into it at some point. Not sure I will have time, so it's not a promise 😄

[a-maze-d]

But just for completeness, a defdelegate function's documentation does not have a typespec.

So my implementation is no different from what we have today.

[josevalim]

But just for completeness, a defdelegate function's documentation does not have a typespec.

Yes, exactly. We removed it precisely because of all of those bugs.

So let's revisit this one once Elixir can do the type rewriting for us. Thank you! <3