New EEP: Module attributes for documentation

[josevalim]

No description provided.

[essen]

First, attributes without parens is weird. :-)

I agree about wanting a different solution than code comments. Comments are not documentation. I disagree about documentation in the source code being easier to keep in sync, it gets out of date just as easily as external documentation. On the other hand when the documentation is in the source code it's easier to sneek in potentially breaking documentation changes unnoticed.

As a result I would much prefer to keep external documentation but still make use of these attributes, perhaps via something like:

-moduledoc({external, "doc/src/manual/my_module.asciidoc"}).
-doc({external, "doc/src/manual/my_module.my_function.asciidoc"}).

This would close any debate about documentation inside or outside the source code since both would be possible. There is also no issues around quotes when using external documentation.

I suppose a compile flag could be added to locate the external files more easily, though . is perfectly fine in my case.

[hauleth]

This probably should strictly describe license, like CC0, as not all jurisdictions allow voluntary assigning document to public domain.

[josevalim]

This is the standard of all other EEPs, so I won't change it, but perhaps this conversation needs to brought up elsewhere? Or maybe it only matters for what is valid in Sweden in this case?

[hauleth]

@josevalim created #25

[richcarl]

AFAIK, the templates were copied from PEP, so this phrasing is likely just an old artefact. I agree it should be changed to CC0. In many countries (including most of Europe) saying "this is placed in the public domain" does not have any legal effect. Copyright is automatic as of the Berne convention of 1988.

[josevalim]

@essen thank you for the comments and the suggestion. I will amend the proposal to allow embedding external documents too. It may be a bit repetitive to provide a path for each doc but I guess someone could write a parse transform that maps everything in a directory to moduledoc+doc if they really want to reduce the duplication?

[KennethL]

another attribute 'include_doc' could be introduced for inclusion of doc written in other files than the source code file. That would make it possible to mix doc written in the source file with doc written outside in a flexible way.

…

On Wed, Jun 2, 2021 at 1:25 PM José Valim ***@***.***> wrote: @essen <https://github.com/essen> thank you for the comments and the suggestion. I will amend the proposal to allow embedding external documents too. It may be a bit repetitive to provide a path for each doc but I guess someone could write a parse transform that maps everything in a directory to moduledoc+doc if they really want to reduce the duplication? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#24 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABFWSF2OCPXZ2BVZ6KEICDTQYIMDANCNFSM456M73PQ> .

[RaimoNiskanen]

An EEP should have line breaks as any Markdown document (that follows E-Mail conventions).
From EEP 33:

You must adhere to the Emacs convention of adding two spaces at the
end of every sentence. You should fill your paragraphs to column 70,
but under no circumstances should your lines extend past column 79.
If your code samples spill over column 79, you should rewrite them.

[josevalim]

@RaimoNiskanen updated!

@essen and @KennethL, I added a section about supporting -doc({file, Path}). There is only one concern: you wouldn't be able to place documentation metadata in an asciidoc file. But I assume that is fine? The metadata is typically License+Author for modules and Since+Deprecated annotations for functions.

[lhoguin]

Yes no problem about metadata.

[ferd]

Any ordering preferences compared to type specs?

[josevalim]

@ferd please expand? I am not sure I follow the question. :)

[ferd]

People have a tendency to do something like:

%% @doc This function turns the programmer into a much more productive one
-spec levelup(programmer()) -> programmer().
levelup(Programmer) -> Programmer*10.

The new literal translation would be:

-doc "This function turns the programmer into a much more productive one".
-spec levelup(programmer()) -> programmer().
levelup(Programmer) -> Programmer*10.

This will work with the spec above if we read "listed once before each function", meaning there can be one -doc attribute before any function and it will get assigned to the one that follows.

However the spec could also force the following if we read it to mean "the doc must be listed once right before each function":

-spec levelup(programmer()) -> programmer().
-doc "This function turns the programmer into a much more productive one".
levelup(Programmer) -> Programmer*10.

[josevalim]

Ah, I see. We don't look at other attributes, so it can be anywhere before a function. I will clarify.

[ferd]

This, to me, would point towards supporting both formats and converting. Erlang strings should represent safe unicode data that can be converted later with unicode:characters_to_binary(CharData) and for the time being provides safe unicode with low syntactic overhead.

[josevalim]

Yeah, I think I agree with you. What about metadata? Should it be automatically rewritten too?

[ferd]

It could make sense. I'd see this as an extension of all Erlang-style things where CharData gets flattened down for you when possible. It would in principle not harm anything as long as you specify you expect data to be UTF-8 compatible, meaning raw strings, binaries in the utf8 encoding, or lists of either of these.

[hauleth]

@josevalim

you wouldn't be able to place documentation metadata in an asciidoc file

ASCIDoc has built-in support for document metadata via attributes. So with "smart enough" implementation the metadata could be stored in the external files as well.

[essen]

I would suggest keeping the external file format implementation not smart to begin with and build upon them later if there's strong interest. Asciidoc attributes are one option, but there's also Hugo-like header variables that work with any file format for example.

[moiseev]

Any thoughts on the warning similar to -compile(warn_missing_spec). now that these docs are known to the compiler?

[josevalim]

@moiseev I have added a section mentioning this feature could also be added in the future too, thanks!

[hauleth]

I would suggest keeping the external file format implementation not smart to begin with and build upon them later if there's strong interest.

@essen that was what I meant. It shouldn't be Erlang concern to understand and extract metadata from documentation, but the documentation processor (external) should be able to achieve something like that in future.

[michalmuskala]

This seems like a fantastic proposal that would simplify dealing with in-code documentation significantly compared to edoc comments. Is there anything I could do to help move this forward?

[KennethL]

Can you please change the file name to eep-0059.md and I will merge this PR so we can refer to it as EEP-59

[josevalim]

@KennethL done! I have also updated some parts with the feedback received in this PR.

[josevalim]

I pushed again to make the linter happy!