diff options
author | Johan Dahlin <jdahlin@async.com.br> | 2008-04-29 11:29:37 +0000 |
---|---|---|
committer | Johan Dahlin <johan@src.gnome.org> | 2008-04-29 11:29:37 +0000 |
commit | bc5755c7746752978dd34cad7454a79e2ff71b35 (patch) | |
tree | 5e7799ad1d9771622bc1a429a1bd6253417201f1 /docs/metadata-annotations-proposal.txt | |
parent | 037f2bb7cf262cbd69a0bd70ff2dc289b1950069 (diff) | |
download | gobject-introspection-bc5755c7746752978dd34cad7454a79e2ff71b35.tar.gz |
Add a basic, unfinshed man page for g-ir-scanner, move documents into .txt
2008-04-29 Johan Dahlin <jdahlin@async.com.br>
* Makefile.am:
* docs/g-ir-scanner.1:
* metadata-annotations-proposal.txt:
* metadata-format.txt:
Add a basic, unfinshed man page for g-ir-scanner, move documents into .txt
svn path=/trunk/; revision=259
Diffstat (limited to 'docs/metadata-annotations-proposal.txt')
-rw-r--r-- | docs/metadata-annotations-proposal.txt | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/docs/metadata-annotations-proposal.txt b/docs/metadata-annotations-proposal.txt new file mode 100644 index 00000000..fba043ee --- /dev/null +++ b/docs/metadata-annotations-proposal.txt @@ -0,0 +1,181 @@ +***FIXME**** +Currently annotations are required to be pooled in one place, +sorted by entry offset. That makes it impossible to add annotations +in incremental manner, making it impossible for dynamic languages +like Python to give correct metadata. We should probably remove that +requirement, and add offset to annotations to each annotatable entry, +this however means 4*n more bytes used :\ +***FIXME**** + + mclasen: Incremental generation of metadata is already + problematic without annotations, since you have to grow the + directory, and we currently assume that local entries + are before remote entries in the directory. + Adding 4 bytes to each type, value and arg blob is certainly + going to blow the size of the metadata up unreasonably, + since these are the most common blob types. + + +Typed annotations: + +struct AnnotationBlob +{ + guint32 entry_offset; + guint32 type; + guint32 values_offset; +}; + +entry_offset: offset of metadata entry (must be valid target for this + annotation) described by this annotation + +type: offset of AttributeBlob describing type of this annotation + +values_offset: offset to n_fields (read from corresponding AttributeBlob) + values of appropriate types, specifying value of this + annotation + + + mclasen: What type of blob is being pointed to here ? + ValueBlob only holds integer types (for use in enums). + For general types, you will probably have to use + ConstantBlobs. + + +typedef enum +{ + function = 1 << 0, + type = 1 << 1, + param = 1 << 2, + value = 1 << 3, + signal = 1 << 4, + property = 1 << 5, + + all = 0x3F, +} AttributeTargets; + + + mclasen: Does "all" mean just all of the above, or + any blob ? Whats the rationale for not allowing annotations + on some blob types ? Wouldn't it be better to specify + the attribut target using the blob type enum (no way to + specify a subset of targets then, but we could still + indicate "all", e.g. as 0) + + +struct AttributeBlob +{ + guint16 blob_type; /* 11 */ + guint deprecated : 1; + guint allow_multiple : 1; + AttributeTargets targets : 6; + guint has_constructor : 1; + guint reserved : 8; + guint32 name; + + GTypeBlob gtype; + guint32 constructor; + guint16 n_fields; + FieldBlob fields[]; +}; + +allow_multiple: if that attribute can be applied multiple times to one + annotated entry. + +targets: bitmask of allowed targets for annotation with this attribute. + Possible targets are: function (including methods), function + parameter, type (that is, object, enum, or interface), value + (constant or variable exposed from metadata), signal or + property. + +has_constructor: if that attribute has constructor. If 0, default constructor + is used. + +name: name of this attribute. + +gtype: GType under which is the attribute registered. + + + mclasen: This is unclear. Why would attributes be registered + in GType ? Do we have a special base type for them ? Do + they need to conform to some interface ? + + +constructor: offset to constructor function for this attribute, or 0 if + default is used. + + + mclasen: This is unclear. Who uses this constructor, and + what is it used for ? + + +n_fields: number of fields this attribute has + + + mclasen: it seems to me that, since we have struct support, + a single field would be sufficient. + + +fields: array of SimpleTypeBlobs describing fields this attribute has. + Only allowed are types for which valid literals exist. Currently + that's the following types: + void + boolean + int8 + uint8 + int16 + uint16 + int32 + uint32 + int64 + uint64 + int + uint + long + ulong + ssize_t + size_t + float + double + utf8 + filename + type + + "type" is guint32 specifying offset to another metadata + entry describing one of: object, interface, enum, function + (including methods), callback, signal or constant. "type" + literals should be exposed to the user either as strings + specyfing fully qualified name of one of above types, + mangled according to rules of language used (if the language + uses any mangling of type names), or type expressed as + valid type literal in syntax of language. + Implementation is responsible for reading such type name and + converting it to correct guint32 value. + + + mclasen: I would be pragmatic and specify types just be + a qualified name, as you already do in your C example below. + But I think there is a case for allowing arrays of basic + types. I could imagine storing the "Since: 2.6" annotation + as { 2, 6 } + + + For example, Python might use the following syntax: + + gobject.annotation(my_container, ContainerTypeAttribute, + type=gobject.GObject) + + Here, my_container is variable of some container class, + ContainerTypeAttribute is hypothetical attribute specifying + specialisation for containers, and type=gobject.GObject says + that this given container will hold GObjects. Python + implementation is now responsible for converting gobject.GObject + into guint32 value pointing to definition of GObject (***FIXME*** + how do we deal with GObject which is fundamental type?). + + The same expressed in C could look as follows: + + G_OBJECT_ANNOTATION(my_container_constant, ContainerTypeAttribute + "type", "GObject.GObject") + + where G_OBJECT_ANNOTATION is hypothetical macro used for marking + annotations for metadata scanner. |