Kuba/ssh/doc fixes/otp 19335

[u3s]

No description provided.

[github-actions]

CT Test Results

    2 files     29 suites   18m 36s ⏱️
  462 tests   458 ✅  4 💤 0 ❌
1 667 runs  1 643 ✅ 24 💤 0 ❌

Results for commit d23db60.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

• Complete CT logs (Download Logs)
• HTML Documentation (Download HTML Docs)
• Windows Installer

// Erlang/OTP Github Action Bot

[IngelaAndin]

My spontaneous question is why do we have a lot types in an .hrl file? I think the types belong in the API module if they are types used in the API. If they are internal types they would probably also belong to some module handling that part of the system rather than and .hrl file. I know this was not your design, I am just questioning if we should keep it when we are improving things.

[u3s]

My spontaneous question is why do we have a lot types in an .hrl file? I think the types belong in the API module if they are types used in the API. If they are internal types they would probably also belong to some module handling that part of the system rather than and .hrl file. I know this was not your design, I am just questioning if we should keep it when we are improving things.

Yes. I wondered as well. I guess one can think of pros of this approach:

• less type code in module implementation file (better argument before docs were included in source)
• not all types from src/*.hrl needs to be exported. some of them might be used as local inside ssh modules ... for example role()

Do you think it is worth to take them out from hrl file? I have no strong opinion.

[IngelaAndin]

You do not have to export all types for a module. Only the ones used by the API. I think having it in an .hrl file hides errors that could otherwise be caught. Maybe some of the types does not need to be types at all. Old documentation promoted making lots of subtypes.

[u3s]

You do not have to export all types for a module. Only the ones used by the API.

but can you internally share type between ssh modules without exporting type out from ssh?

I think having it in an .hrl file hides errors that could otherwise be caught. Maybe some of the types does not need to be types at all. Old documentation promoted making lots of subtypes.

I will have a 2nd look on this.

[IngelaAndin]

You do not have to export all types for a module. Only the ones used by the API.

but can you internally share type between ssh modules without exporting type out from ssh?

The you can put them in a none API module that make sense and export them from there just as we have functions
in non API modules exported for the applications internal use.

I think having it in an .hrl file hides errors that could otherwise be caught. Maybe some of the types does not need to be types at all. Old documentation promoted making lots of subtypes.

I will have a 2nd look on this.

👍