Documentation?

[p-mongo]

Does any documentation exist for Fiddle beyond the content at https://ruby-doc.org/stdlib-2.7.0/libdoc/fiddle/rdoc/Fiddle.html ?

If not, is there interest in documentation contributions, and if so in what format/structure?

[kou]

Here: https://github.com/ruby/fiddle/blob/master/ext/fiddle/fiddle.c#L132-L164

is there interest in documentation contributions

Yes.

and if so in what format/structure?

RDoc format.

[chrisseaton]

@p-mongo can you give some more concrete indication of what documentation you think is missing and we'll look at adding it. Otherwise this issue isn't very specific or actionable.

[p-mongo]

Considering, for example, https://github.com/ffi/ffi/wiki/Features-at-a-Glance:

• How to create C structs to pass to C code
• How to reference fields in structs created by C code
• Same for unions
• How to pass Ruby methods as callbacks to C code
• How to use variadic functions

[rubyFeedback]

Since chris asked, I'd like to add some things to this, rather than create a new issue. It is not solely
confined to documentation alone, but more inclusive in the sense of "what can we do with fiddle".

keep in mind that many ruby users do not know C. For instance, I don't really. I can read some C
code and understand what is going on, but when it comes to pointers it's game over for me.

Still, I managed to have a use case to suddenly use Fiddle::Pointer - and, actually, duck patch
it ("monkey patch") specifically for libui.

Libui is a cross-platform GUI that is quite minimal. kojix2 maintains the ruby bindings for it and
I think kou already is aware of some of the issues / problems. In particular if you look at the
libui gem by kojix2, some examples require assignment to variables to prevent GC kicking
in. I played with the code and indeed, when I removed the assignment parts, the program
crashed. With these assignments still in place, the program did not crash.

This is not very elegant to have to write ruby code that prevents segfaults induced by
anti-GC methods IMO. So this is one use case.

It's not so much just about static documentation but trying to explain what could be done
about this. See https://github.com/kojix2/LibUI/blob/main/examples/histogram.rb past
line 133 where kojix2 mentions it; I don't remember where he discussed this with
kou but it's at some github issue discussion if I remember correctly.

But I also have a second use case for asking for better documentation in this
regard.

In my own crappy gem add-on to libui here at
https://rubygems.org/gems/libui_paradise
I modify Fiddle::Pointer. I was surprised to see that this
works. Now that is mega-hackish; I don't recommend anyone
ever do this ... but I don't know of another way right now.

In ruby-gtk I was used to:

box1.add(box2)

But I can't do that with Fiddle::Pointer per se, in the sense that I don't know
how to do proper "subclasses" or "widgets" of a Fiddle::Pointer.

For instance I don't think I can easily do:

class FancyButton < Libui

I also don't feel fine modifying Fiddle::Pointer directly, but how can I
"integrate" proper subclasses or use a OOP-centric layout? I really
have no idea right now.

In some ways this is fun to play with fiddle, but on the other hand it
feels a bit hackish overall, like we write ruby code that is actually
C code.

This is just one example or two examples really. I am sure there are
more use cases and what not.

I have absolutely no idea about the internals, but perhaps the ruby
core team as well as people who know C very well (and ruby-gtk
too such as kou) can understand the problem domain. A lot of
ruby evidently requires a lot of domain-specific knowledge, e. g.
I still think mruby caters mostly to people who know C fairly
well. I don't expect that fiddle is for "xyz average ruby programmer",
but my hope is that in the long run fiddle can be brought to a
situation where even average ruby folks may understand how to
work with it or adapt it to make working with fiddle almost feel like
"full ruby" (including OOP-centric aspects when writing code; see
the example of box1.add(box2) versus calling toplevel methods
such as UI.create_paned_something() and what not).