Re: API doc / Doygen ssh_channel_callbacks_struct missing

[Jakub Jelen <jjelen@xxxxxxxxxx>]

Hi and welcome to libssh!

I think it is a overlook. The source code has annotation for all the
fields of the structure, but does not have a leading doxygen comment
block before the structure, which prevents it being compiled into the
documentation, I think:

https://gitlab.com/libssh/libssh-mirror/-/blob/master/include/libssh/callbacks.h?ref_type=heads#L850

Do either of you want to submit a MR to add some description and
verify that adding the comment will make the structure rendered in the
documentation?

Regarding the wording of add/set, I think this could be also
clarified. The set() actually differs from the add() only with the
fact that it prepends the callback instead of appending, if I see
right in the code and neither of them replaces the previously set
callbacks. If you have some wording that can improve this, please open
a merge request with proposed changes.

Thank you,
Jakub

On Sun, Mar 16, 2025 at 5:39 PM <g4-lisz@xxxxxxxxxxxx> wrote:
>
> Hi Abhiram,
>
> You're very welcome! And thank you for the confirmation regarding the ssh_sockets.
>
> By the way: IMHO the wording of ssh_set_channel_callbacks() and ssh_add_channel_callbacks() is inverted: "To add" implies that the CB are in _addition_ to the existing callbacks, while setting them should replace the existing...
>
> Cheers
> Till
>
> March 16, 2025 4:33 PM, "Bangaru Abhi" <abhiram162005@xxxxxxxxx> wrote:
>
> Dear Till,
>
> Thank you for your email and for pointing out the missing `ssh_channel_callbacks_struct` in the API documentation. I will ensure that the struct is added. Your attention to detail is greatly appreciated!
>
> Regarding the `ssh_socket` functions, you are correct in your assumption. These functions are intended for internal use.
>
> Thank you again for your valuable feedback.
>
> Sincerely,
> Abhiram
> On Sun, 16 Mar 2025 at 20:10, <g4-lisz@xxxxxxxxxxxx> wrote:
>
> Hi there,
>
> I wonder why struct ssh_channel_callbacks_struct is missing in the API doc (https://api.libssh.org/stable/group__libssh__callbacks.html).
>
> Maybe this is a small fix in the annotations and it would help the API doc a lot...
>
> Talking about documentation: I was wondering when / what for to use ssh_socket functions. They're not mentioned in the tutorial. Are they used internally only?
>
> Cheers
> Till
>
>
>
>
>