User manuals seem to be outdated

Questions / Help
,
1

I see some of the user manuals do not list all the functions implemented by a module. Why is this? Are the manuals outdated? or the functions are deprecated and hence, not listed in the user manual?

For example; Refer to the ssh user manual. Erlang shell lists the function ssh_connection:channel_data, whereas ssh_connection.html does not list.

Erlang shell lists as follows;

(node1@vm-alarm)7> ssh_connection:
functions
adjust_window(                    channel_adjust_window_msg(        channel_close_msg(                channel_data(                     channel_data_msg(                 
channel_eof_msg(                  channel_failure_msg(              channel_open_confirmation_msg(    channel_open_failure_msg(         channel_open_msg(                 
channel_request_msg(              channel_status_msg(               channel_success_msg(              close(                            decode_pty_opts(                  
dummy(                            encode_ip(                        encode_pty_opts(                  exec(                             exit_status(                      
handle_msg(                       handle_stop(                      module_info(                      open_channel(                     ptty_alloc(                       
reply_request(                    request_failure_msg(              request_global_msg(               request_success_msg(              send(                             
send_environment_vars(            send_eof(                         session_channel(                  setenv(                           shell(                            
signal(                           subsystem(                        window_change(
1 Like
2

Those are internal functions that have been exported for technical reasons. They’re only meant to be used by other modules within the ssh application and thus aren’t documented.

Shell expansion looks at all exported functions and doesn’t make any clever attempts to hide functions like these.

4 Likes
3

IMHO code is not documentation and when looking for what to use I tend to rely on documentation only instead of LSP-s, completion tools and such. That is especially true in erlang. For the reasons @jhogberg mentioned some functions needs to be exported but are not intended to be used by user.

For further information you can look at Eep 0005 - Erlang/OTP, and watch out for the upcoming work done by @mmin (spoilers: it is very exiting and good) on how to deal with exports so that this confusion about intent can be avoided (or intent even be enforced) in the future.

2 Likes
4

Maybe it could make sense to hide these in tab-completion (at least by default)? I.e. lift the “undocumented” bit to an attribute that embeds this information in the module info?

2 Likes
5

I believe this is exactly what @kuna.prime is hinting will happen once the work @mmin is doing is merged.

Of course I had to go searching for it, so spoiler: https://github.com/erlang/otp/compare/master…MarkoMin:otp:feat/static-eep5/internal_export

Exciting stuff!!

2 Likes