API reference for ruby LibUI?

[rubyFeedback]

Hey there libui-folks,

If you look at rubygems.org for libui, you get to the documentation entry, and then a link towards,
for instance, this website:

https://www.rubydoc.info/gems/libui/0.1.2/LibUI

This contains some useful information, such as:

TextStretchSemiExpanded = 5

or

https://www.rubydoc.info/gems/libui/0.1.2/LibUI.open_type_features_add

.open_type_features_add(otf, a, b, c, d, value) ⇒ Object

(Useful for an API / reference point of view.)

However had, I also ran this tiny .rb script just now:

require 'libui'

pp LibUI.methods.sort

And I got all the toplevel methods sorted, here:

 :set_temporary_name,
 :singleton_class,
 :singleton_class?,
 :singleton_method,
 :singleton_methods,
 :slider_has_tool_tip,
 :slider_on_changed,
 :slider_on_released,
 :slider_set_has_tool_tip,
 :slider_set_range,
 :slider_set_value,
 :slider_value,
 :spinbox_on_changed,
 :spinbox_set_value,
 :spinbox_value,
 :tab_append,
 :tab_delete,
 :tab_insert_at,
 :tab_margined,
 :tab_num_pages,
 :tab_set_margined,
 :table_append_button_column,
 :table_append_checkbox_column,
 :table_append_checkbox_text_column,
 :table_append_image_column,
 :table_append_image_text_column,
 :table_append_progress_bar_column,
 :table_append_text_column,
 :table_column_set_width,
 :table_column_width,
 :table_get_selection,
 :table_get_selection_mode,
 :table_header_on_clicked,
 :table_header_set_sort_indicator,
 :table_header_set_visible,
 :table_header_sort_indicator,
 :table_header_visible,
 :table_model_row_changed,
 :table_model_row_deleted,
 :table_model_row_inserted,
 :table_on_row_clicked,
 :table_on_row_double_clicked,
 :table_on_selection_changed,
 :table_set_selection,
 :table_set_selection_mode,
 :table_value_color,
 :table_value_get_type,
 :table_value_image,
 :table_value_int,
 :table_value_string,
 :tap,
 :then,
 :timer,
 :to_enum,
 :to_s,
 :undef_method,
 :undefined_instance_methods,
 :uninit,
 :user_bug_cannot_set_parent_on_toplevel,
 :window_borderless,
 :window_content_size,
 :window_focused,
 :window_fullscreen,
 :window_margined,
 :window_on_closing,
 :window_on_content_size_changed,
 :window_on_focus_changed,
 :window_resizeable,
 :window_set_borderless,
 :window_set_child,
 :window_set_content_size,
 :window_set_fullscreen,
 :window_set_margined,
 :window_set_resizeable,
 :window_set_title,
 :window_title,
 :yield_self]

And about three hundred method names more.

But ... where can we read up documentation about these?

For many it is easy to figure out what it means, e. g.

LibUI.window_set_title()

Is for setting a title. :)

But for several others, one has to make a guess.

I understand that the ruby code wraps over the C code, which in itself
is not massively documented either, going down to andlabs not documenting
everything in his spare time, but ... can we improve on the documentation
somehow? Ideally even with some examples.

I can implement helper-code in my own libui-wrapper (it is currently not
on rubygems.org; I intend to eventually have it all back up on github,
but right now reallife delays this, so it may take a little more time before
my old code is all back up again), but often I am not entirely certain what
to do, and looking up at the official C sources of libui-ng is ... well, you kind
of need to know C and I am not really good at C. Sometimes I can infer
from the names or the body of a function, but often I really don't know what
to do, and libui-ng also lacks examples, unfortunately. The ruby gem has
various examples, but I think not for every method listed above.

Could we build up a more complete API reference for ruby LibUI? If so, how
can we go about this for methods that are not clear or easy to understand?
In what format could this API reference be made? Ideally it could be hosted
directly at https://www.rubydoc.info/, but the format of rubydoc isn't that
great either, so I am not sure what to do in order to improve it.

The end goal should be that every method exposed by C libui-ng, can also be
documented in ruby - at the least with one working (small) example. Ideally
also with one or two sentences about the job of this, in particular for those
methods that are not easy to understand instantly, such as:

:attribute_family
:attributed_string_grapheme_to_byte_index
:control_enabled_to_user
:draw_matrix_transform_point

and various other methods like that. (For those that are easier to understand,
we can perhaps skip writing too much documentation, but method names that
are strange, should ideally have some kind of explanation. Perhaps having an
example is more important, as people can figure out things on their own if
an example is to the point. For instance, one example for .draw_matrix_transform_point;
I assume it has to do with free drawing, but what example could showcase this?)

[AndyObtiva]

I built Glimmer DSL for LibUI by using all features of the Ruby LibUI binding without having any issues with missing documentation. That's because I knew that it was an FFI binding, so the full documentation is available in this file:
https://github.com/kojix2/LibUI/blob/main/lib/libui/ffi.rb

This follows the Agile principle of "self-documenting code", which obviates the need for extra documentation:
https://dev.to/mattlewandowski93/writing-self-documenting-code-4lga

Additionally, I relied on the libui-ng headers:
https://github.com/libui-ng/libui-ng/blob/master/ui.h

And, I go to girb (Glimmer IRB) and run this command every once in a while when I need to remember some methods from the LibUI Ruby binding:

LibUI.methods.sort - Object.methods

Outputs:

 => 
[:alloc_control,                                                                          
 :append_features,                                                                        
 :area_begin_user_window_move,                                                            
 :area_begin_user_window_resize,                                                          
 :area_queue_redraw_all,                                                                  
 :area_scroll_to,                                                                         
 :area_set_size, 
 ...

In fact, I put all those low-level methods in the Glimmer DSL for LibUI README for quick reference in general:
https://github.com/AndyObtiva/glimmer-dsl-libui?tab=readme-ov-file#original-api

I think the cost/benefit ratio for implementing additional full documentation is too high. But, LibUI is a community open-source project, so if you have the time for it, you are welcome to be helpful by adding extra Ruby documentation or implement a doc build automatically from the FFI files or C headers.

In any case, the recommended way to use LibUI the productive Ruby way is by relying on Glimmer DSL for LibUI, which simplifies the usage of LibUI significantly and removes the need for you to know about all the low-level details. It's like you don't use Assembly language programming in day-to-day programming because it's too low-level, requiring very verbose expensive to maintain code while taking much longer to finish work, which is why you use higher-level programming languages. Glimmer similarly offers a DSL that is higher level than low-level binding programming. Devs who know the DSL can build apps in a fraction of the time and with much more readable and maintainable code. The recommended way to learn Glimmer DSL for LibUI is to go through all its samples as they provide near 100% coverage of all LibUI features (and, the README covers any missing things usually, so practically speaking, nothing that matters should be missing). And, then try to change those samples to suit your application needs. There is also a wealth of extra tutorials for Glimmer DSL for LibUI like the RubyConf 2022 talk and the RubyConf 2023 workshop. If you get stuck after that and need help with a specific application you are building, hit me up about it in Glimmer Gitter chat provided you provide app code and ask me specific questions about a specific app you are building, not some random questions without code.

[kojix2]

Thank you for your comment.

I understand that RubyFeedback values documentation using Yard very much. It seems that your work revolves more around that than GitHub. However, I simply don’t have the time to maintain documentation.

In the past, I worked on a project called GR.rb (which, like LibUI, uses Fiddle and also provides Ruby-FFI-like features through the Fiddley module), and I aimed for perfect documentation. However, I failed. The reason was that I couldn’t allocate enough time and energy to keep up with changes upstream.

Andy put it concisely:

I think the cost/benefit ratio for implementing additional full documentation is too high.

But, LibUI is a community open-source project, so if you have the time for it, you are welcome to be helpful by adding extra Ruby documentation or implement a doc build automatically from the FFI files or C headers.

On the other hand, from my perspective, programming for RubyFeedback seems to be like a personal oasis, an artistic activity where you build your own pyramid. It seems that productivity isn’t much of a concern for you, and I can understand that. After all, doing bioinformatics with Ruby, as I do, could also be seen as a rather ridiculous pursuit from an objective point of view.

My real job is in medical research, and while I often slack off and play with computers, the time I can spend on open-source software is limited, and it gets smaller every year.

Please refer to the full libui-ng documentation when needed. I do that as well. To be honest, I’m just connecting C functions to Ruby methods and don’t really understand libui. Running the libui-ng code line by line takes immense patience. Andy might have done it.

But honestly, I don’t think there’s anyone on earth who fully understands libui-ng. The original author of libui might come the closest, but they have probably forgotten most of the project by now. Plus, many new functions have been added to libui-ng, so it’s doubtful that even they fully understand it anymore.

Nobody else fully understands it either. There are many things like this in the world...

Your replies on GitHub often feel more like casual letters than technical discussions expected in the issue section.

Some people may not like that, but I love it.
I don’t know where you are in the world, but maybe somewhere in Eastern Europe?
Please continue your great work!

(Translate from Japanese to English with ChatGPT 4o)