Erlang OTP 23.0-rc1 is available for testing

Tue Mar 3 18:26:03 CET 2020

Roberto,

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.

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):

---------- Forwarded message ---------
From: Kenneth Lundin <kenneth@REDACTED>
Date: Fri, 28 Feb 2020 at 07:31
Subject: Re: Erlang OTP 23.0-rc1 is available for testing

edoc is the tool which can handle documentation embedded into the source
code and generate documentation for it. Work is going on to
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.

So you already can embed documentation in the .erl files.

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.

/Kenneth, Erlang/OTP team,  Ericsson

On Fri, 28 Feb 2020 at 18:15, Roberto Aloi <prof3ta@REDACTED> wrote:

> Hi Karl,
>
> Erlang has EDoc (
> http://erlang.org/doc/apps/edoc/chapter.html) which allows you to do just
> that. Or are you referring to something else?
>
> Best,
>
> Roberto
>
> On Fri, 28 Feb 2020 at 06:51, Karl Velicka <karolis.velicka@REDACTED>
> wrote:
>
>> Hi Kenneth,
>>
>> Great to hear about the new release - thank you and the team!
>>
>> 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?
>>
>> Thanks,
>> Karl
>>
>> On Thu, 27 Feb 2020 at 13:38, Kenneth Lundin <kenneth@REDACTED> wrote:
>>
>>> OTP 23 Release Candidate 1
>>>
>>> This is the first of three planned release candidates before the OTP 23
>>> release.
>>> The intention with this release is to get feedback from our users. All
>>> feedback is welcome, even if it is only to say that it works for you.
>>>
>>> Erlang/OTP 23 is a new major release with new features, improvements as
>>> well as a few incompatibilities.
>>> Potential Incompatibilities
>>>
>>>    - SSL:
>>>       - Support for SSL 3.0 is completely removed.
>>>       - TLS 1.3 is added to the list of default supported versions.
>>>    - erl_interface: Removed the deprecated parts of erl_interface
>>>    (erl_interface.h and essentially all C functions with prefix erl_).
>>>    - The deprecated erlang:get_stacktrace/0 BIF now returns an empty
>>>    list instead of a stacktrace.
>>>    erlang:get_stacktrace/0 is scheduled for removal in OTP 24.
>>>    - ...
>>>
>>> Highlights
>>>
>>>    - A new module erpc in kernel which implements an enhanced subset of
>>>    the operations provided by the rpc module. Enhanced in the sense
>>>    that it makes it possible to distinguish between returned value, raised
>>>    exceptions and other errors. erpc also has better performance and
>>>    scalability than the original rpc implementation. This by utilizing
>>>    the newly introduced spawn_request() BIF. Also the rpc module
>>>    benefits from these improvements by utilizing erpc when possible.
>>>    - Scalability and performance Improvements plus new functionality
>>>    regarding distributed spawn operations.
>>>    - In binary matching, the size of the segment to be matched is now
>>>    allowed to be a guard expression (EEP-52)
>>>    - When matching with maps the keys can now be guard expressions
>>>    (EEP-52).
>>>    - 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.
>>>    - Allow underscores in numeric literals to improve readability.
>>>    Examples: 123_456_789, 16#1234_ABCD.
>>>    - New functions in the shell for displaying documentation for Erlang
>>>    modules, functions and types. The
>>>    functions are:
>>>       - h/1,2,3 -- Print the documentation for a Module:Function/Arity.
>>>       - ht/1,2,3 -- Print the type documentation for a Module:Type/Arity
>>>       .
>>>       The embedded documentation is created as docchunks (EEP 48) when
>>>       building the Erlang/OTP documentation.
>>>    - kernel: The module pg with a new implementation of distributed
>>>    named process groups is introduced. The old module pg2 is deprecated
>>>    and scheduled for removal in OTP 24.
>>>    - 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.
>>>    - ...
>>>
>>> For more details see
>>> http://erlang.org/download/otp_src_23.0-rc1.readme
>>>
>>> Pre built versions for Windows can be fetched here:
>>> http://erlang.org/download/otp_win32_23.0-rc1.exe
>>> http://erlang.org/download/otp_win64_23.0-rc1.exe
>>>
>>> Online documentation can be browsed here:
>>> http://erlang.org/documentation/doc-11.0-rc1/doc
>>> The Erlang/OTP source can also be found at GitHub on the official Erlang
>>> repository,
>>> https://github.com/erlang/otp
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20200303/62c0db3e/attachment.htm>