Document CStruct vs CStructEntity
chrisseaton opened this issue · comments
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.
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.
Ah, I got it. The creator wants to hide implementation details.
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.
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?
I think I've clarified this in #41.
OK.
I close this.