New EEP: Module attributes for documentation

[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.

[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 https://github.com/erlang/eep/pull/24#issuecomment-852946791, 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.

[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!