<div dir="ltr"><div>Roberto,</div><div><br></div><div>I was vaguely aware of EDoc but it's a tool that allows you to generate docs from source, but not embed docs _in_ source. That is, (according to my understanding at least) Elixir's @doc mechanism actually embeds the relevant documentation files in the beam files during compilation. I was interested in Erlang's plans (or lack thereof) for something equivalent.</div><div><br></div><div>Kenneth did reply to me off-list with some thoughts on this so I really hope he doesn't mind me sharing them with the list (in case there's more readers wondering the same thing as I):</div><div><br></div><div><div dir="ltr" class="gmail_attr">---------- Forwarded message ---------<br>From: <b class="gmail_sendername" dir="auto">Kenneth Lundin</b> <span dir="auto"><<a href="mailto:kenneth@erlang.org">kenneth@erlang.org</a>></span><br>Date: Fri, 28 Feb 2020 at 07:31<br>Subject: Re: Erlang OTP 23.0-rc1 is available for testing<br></div><br><div dir="ltr">edoc is the tool which can handle documentation embedded into the source code and generate documentation for it. Work is going on to<div>make edoc generate the same format (docchunks ala EEP 48) as from the OTP docs and making it available in the same way from the shell and editors etc.</div><div><br></div><div>So you already can embed documentation in the .erl files. </div><div><br></div><div>The exact format in the .erl files might evolve to something more integrated with the language like Elixir, but the first step is to generate the same docchunks from Edoc.</div><div><br></div><div>/Kenneth, Erlang/OTP team,  Ericsson</div></div></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, 28 Feb 2020 at 18:15, Roberto Aloi <<a href="mailto:prof3ta@gmail.com">prof3ta@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div dir="auto">Hi Karl,</div></div><div dir="auto"><br></div><div dir="auto">Erlang has EDoc (<div><a href="http://erlang.org/doc/apps/edoc/chapter.html" target="_blank">http://erlang.org/doc/apps/edoc/chapter.html</a>) which allows you to do just that. Or are you referring to something else?</div><div dir="auto"><br></div><div dir="auto">Best,</div><div dir="auto"><br></div><div dir="auto">Roberto</div><div dir="auto"><br></div></div><div><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, 28 Feb 2020 at 06:51, Karl Velicka <<a href="mailto:karolis.velicka@gmail.com" target="_blank">karolis.velicka@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div dir="auto">Hi Kenneth,</div></div><div dir="auto"><br></div><div dir="auto">Great to hear about the new release - thank you and the team!</div><div dir="auto"><br></div><div dir="auto">The point about the documentation display functions raises a question though - are there any plans to add a mechanism for embedding documentation within erl source files? Something similar to elixir’s @doc system perhaps?</div><div dir="auto"><br></div><div dir="auto">Thanks,</div><div dir="auto">Karl</div><div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, 27 Feb 2020 at 13:38, Kenneth Lundin <<a href="mailto:kenneth@erlang.org" target="_blank">kenneth@erlang.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><h2 style="box-sizing:border-box;margin-bottom:16px;line-height:1.25;padding-bottom:0.3em;border-bottom:1px solid rgb(234,236,239);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";margin-top:0px;color:rgb(36,41,46)">OTP 23 Release Candidate 1</h2><h2 style="box-sizing:border-box;margin-bottom:16px;line-height:1.25;padding-bottom:0.3em;border-bottom:1px solid rgb(234,236,239);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";margin-top:0px;color:rgb(36,41,46)"><p style="box-sizing:border-box;margin-top:0px;margin-bottom:16px;font-size:14px;font-weight:400;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">This is the first of three planned release candidates before the OTP 23 release.<br style="box-sizing:border-box">The intention with this release is to get feedback from our users. <span style="box-sizing:border-box;font-weight:600;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">All feedback is welcome</span>, even if it is only to say that it works for you.</p><p style="box-sizing:border-box;margin-top:0px;margin-bottom:16px;font-size:14px;font-weight:400;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Erlang/OTP 23 is a new major release with new features, improvements as well as a few incompatibilities.</p></h2><h3 style="box-sizing:border-box;margin-top:24px;margin-bottom:16px;font-size:1.25em;line-height:1.25;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(36,41,46)">Potential Incompatibilities</h3><h2 style="box-sizing:border-box;margin-bottom:16px;line-height:1.25;padding-bottom:0.3em;border-bottom:1px solid rgb(234,236,239);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";margin-top:0px;color:rgb(36,41,46)"><ul style="box-sizing:border-box;padding-left:2em;margin-top:0px;margin-bottom:16px;font-size:14px;font-weight:400;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><li style="box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">SSL:<ul style="box-sizing:border-box;padding-left:2em;margin-top:0px;margin-bottom:0px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><li style="box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Support for SSL 3.0 is completely removed.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">TLS 1.3 is added to the list of default supported versions.</li></ul></li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erl_interface</code>: Removed the deprecated parts of <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erl_interface</code><br style="box-sizing:border-box">(<code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erl_interface.h</code> and essentially all C functions with prefix <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erl_</code>).</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">The deprecated <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erlang:get_stacktrace/0</code> BIF now returns an empty list instead of a stacktrace.<br style="box-sizing:border-box"><code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erlang:get_stacktrace/0</code> is scheduled for removal in OTP 24.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">...</li></ul></h2><h3 style="box-sizing:border-box;margin-top:24px;margin-bottom:16px;font-size:1.25em;line-height:1.25;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(36,41,46)">Highlights</h3><h2 style="box-sizing:border-box;margin-bottom:16px;line-height:1.25;padding-bottom:0.3em;border-bottom:1px solid rgb(234,236,239);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";margin-top:0px;color:rgb(36,41,46)"><ul style="box-sizing:border-box;padding-left:2em;margin-top:0px;margin-bottom:16px;font-size:14px;font-weight:400;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><li style="box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">A new module <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erpc</code> in kernel which implements an enhanced subset of the operations provided by the <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">rpc</code> module. Enhanced in the sense that it makes it possible to distinguish between returned value, raised exceptions and other errors. <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erpc</code> also has better performance and scalability than the original <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">rpc</code> implementation. This by utilizing the newly introduced <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">spawn_request()</code> BIF. Also the <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">rpc</code> module benefits from these improvements by utilizing <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">erpc</code> when possible.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Scalability and performance Improvements plus new functionality regarding distributed spawn operations.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">In binary matching, the size of the segment to be matched is now allowed to be a guard expression (EEP-52)</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">When matching with maps the keys can now be guard expressions (EEP-52).</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">ssh: support for TCP/IP port forwarding, a.k.a tunneling a.k.a as tcp-forward/direct-tcp is implemented. In the OpenSSH client, this corresponds to the options -L and -R.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Allow underscores in numeric literals to improve readability. Examples: <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">123_456_789</code>, <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">16#1234_ABCD</code>.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">New functions in the shell for displaying documentation for Erlang modules, functions and types. The<br style="box-sizing:border-box">functions are:<ul style="box-sizing:border-box;padding-left:2em;margin-top:0px;margin-bottom:0px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><li style="box-sizing:border-box;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">h/1,2,3</code> -- Print the documentation for a <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">Module:Function/Arity</code>.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji""><code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">ht/1,2,3</code> -- Print the type documentation for a <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">Module:Type/Arity</code>.<br style="box-sizing:border-box">The embedded documentation is created as docchunks (EEP 48) when building the Erlang/OTP documentation.</li></ul></li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">kernel: The module <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">pg</code> with a new implementation of distributed named process groups is introduced. The old module <code style="box-sizing:border-box;font-family:SFMono-Regular,Consolas,"Liberation Mono",Menlo,monospace;font-size:11.9px;padding:0.2em 0.4em;margin:0px;border-radius:3px;background-color:rgba(27,31,35,0.047)">pg2</code> is deprecated and scheduled for removal in OTP 24.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Our tool chain for building the Windows packages is upgraded with new C++ compiler, Java compiler, OpenSSL libraries and wxWidgets versions. We are now using WSL (the Linux Subsystem for Windows when building) which makes it easier to handle the build environment.</li><li style="box-sizing:border-box;margin-top:0.25em;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">...</li></ul><p style="box-sizing:border-box;margin-top:0px;margin-bottom:16px;font-size:14px;font-weight:400;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">For more details see<br style="box-sizing:border-box"><a href="http://erlang.org/download/otp_src_23.0-rc1.readme" rel="nofollow" style="box-sizing:border-box;text-decoration-line:none;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(3,102,214)" target="_blank">http://erlang.org/download/otp_src_23.0-rc1.readme</a></p><p style="box-sizing:border-box;margin-top:0px;margin-bottom:16px;font-size:14px;font-weight:400;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Pre built versions for Windows can be fetched here:<br style="box-sizing:border-box"><a href="http://erlang.org/download/otp_win32_23.0-rc1.exe" rel="nofollow" style="box-sizing:border-box;text-decoration-line:none;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(3,102,214)" target="_blank">http://erlang.org/download/otp_win32_23.0-rc1.exe</a><br style="box-sizing:border-box"><a href="http://erlang.org/download/otp_win64_23.0-rc1.exe" rel="nofollow" style="box-sizing:border-box;text-decoration-line:none;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(3,102,214)" target="_blank">http://erlang.org/download/otp_win64_23.0-rc1.exe</a></p><p style="box-sizing:border-box;margin-top:0px;font-size:14px;font-weight:400;margin-bottom:0px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji"">Online documentation can be browsed here:<br style="box-sizing:border-box"><a href="http://erlang.org/documentation/doc-11.0-rc1/doc" rel="nofollow" style="box-sizing:border-box;text-decoration-line:none;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(3,102,214)" target="_blank">http://erlang.org/documentation/doc-11.0-rc1/doc</a><br style="box-sizing:border-box">The Erlang/OTP source can also be found at GitHub on the official Erlang repository,<br style="box-sizing:border-box"><a href="https://github.com/erlang/otp" style="box-sizing:border-box;text-decoration-line:none;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji";color:rgb(3,102,214)" target="_blank">https://github.com/erlang/otp</a></p></h2></div>
</blockquote></div></div>
</blockquote></div></div>
</blockquote></div>