Document CStruct vs CStructEntity

[chrisseaton]

I understand what CStructEntity is - it's a subclass of pointer that points to an instance of the structure in memory.

I don't really understand what CStruct is. It's an object that has a method that returns that subclass of pointer that you want to instantiate. Why not just pass the subclass of pointer in? Why have this entity_class indirection?

Could we write Fiddle::CStructBuilder.create(CUnion, types, members) instead of Fiddle::CStructBuilder.create(Fiddle::CUnion, types, members)?

I know about backwards compatibility concerns, but I don't understand the original intention behind this, and it isn't documented, and even as an FFI and Ruby expert I find it extremely confusing.

I also wish CStructEntity was CStructPointer, but again backwards compatibility I guess.

[kou]

I don't understand the real reason for CStruct and CStructEntity because I'm not the create of CStruct.
But I think that the creator wants to avoid class CUnion < CStruct inheritance.

They exist for backward compatibility of DL (ruby-dl2): https://github.com/ruby/ruby/blob/ruby_2_1/ext/dl/lib/dl/struct.rb

ruby-dl uses Struct and Union directly and class Union < Struct: https://github.com/ruby/ruby/blob/ruby_1_8_7/ext/dl/lib/dl/struct.rb

Anyway, we'll be able to improve them with keeping backward compatibility.

Normal users will use Fiddle::Importer.struct instead of using Fiddle::CStructBuilder.create directly.

[kou]

Ah, I got it. The creator wants to hide implementation details.

[chrisseaton]

The problem is that these terms are super vague. 'entity'? That could mean anything or nothing. Here, an 'entity' is really a pointer to an instance of a type.

And CStruct is really a sort of factory... an object that supplies something used in a constructor. It could be a symbol like :struct instead.

[kou]

What do you want to do in this issue?
Do you want to add more documents?
Do you want to reconstruct lib/fiddle/struct.rb?

[chrisseaton]

I think I've clarified this in #41.

[kou]

OK.
I close this.