Example of how to extend a File entity by attaching a field to it

I guess the best place for this might be the Examples module? If not, then probably the on-line documentation? Or where were you thinking this documentation should be put, assuming someone figures out the answer to your question and wants to write this documentation?

Reassigning to the Examples project.

I hadn't gone through https://drupal.org/node/474420 which is just fantastic !
There I even learnt things from simple comments like // Fields created through Field UI are prefixed with 'field_'

I understood (or rather "realized") that 'text', 'audio' where bundles of the file entity, rather than considering File from a 'node entity point of view' and all went fluently.
I saw the "description" text-input appearing in URL/file/$fid/edit ! then I got a big push of endorphin, proportioned to the liters of sweat my brain left on the keyboard these last days.

At the same time I also realized the logic behind EntityFieldQuery.

So, I think that before closing as "RTFM" :

• the above mentioned page should be linked (or code ported) somewhere into the examples module.
• the fact that 'file' is an entity and file type its bundles is *very* important (but I just discovered it even if, by its name alone, the file_entity module should have helped me), ie:
<?php
field_info_instance("node", "mymodule_description", "file");
// versus
field_info_instance("file", "mymodule_description", "audio");
?>
• in an attempt to be exhaustive, a EntityFieldQuery could be written which, once the field is created, may looks like:
<?php
$field_name = "mymodule_description";
$query->entityCondition("entity_type", "file")->entityCondition("bundle", array("video", "text"), 'IN')->fieldCondition($field_name, "value", "description for file 42")->execute();
?>
• an example of how fields are expected to be structured like according to multivalued and/or multi-language settings:
<?php
$a = file_load(42);
$a->mymodule_description[LANGUAGE_NONE][0] = "description for file 42";
// ? or $a->mymodule_description[LANGUAGE_NONE] = "description for file 42";
// ? or $a->mymodule_description = "description for file 42";
file_save($a);
?>
(but none of the above three work well (with the 1st syntax, only the first character is inserted, like said in the original subject), probably a subtle convention about entity field structure)...
but I don't worry anymore and I'm confident I'll find the explanation soon, maybe hook_file_insert or field_attach_insert() are the way to go in D7 instead of manipulating object attributes manually ?

thx for having replied and pointed me to the right (and after all quite obvious) place, I still have a long road ahead.

I'm back here with some other confusing things about the Field API :
The introduction about the Field API [1] states that:

The Field API defines two primary data structures, Field and Instance, and the concept of a Bundle.

There one dramatically missing word : "Field Type" !

Taken from hook_field_info [2], we can see that it defines a Field Type, like Date creates a datetime field type.
That's confusing that hook_field_info create a field type which IHMO should be called hook_datatype
or so as it's related to the schema. (see below about inconsistency)

But looking at field_example_field_info [3] I can't see it does clearly. It defines a widget, a formatter and a label
but it does not state which "type" of data it stores. It leaves this to field_example_field_schema in the .install file.

So its still difficult to understanding what's a field. As it's a sensible subject, each page of documentation should
not forget to state how/what things are : in-code, in-database, abstract model or implementation (of something).
I still can't find an image illustrating all this, that's what make very hard to understand Drupal's big picture.
The terms primitive datatype, object, class, struct, ... are far less ambiguous and should be preferred.
As we are talking about datatype it would be helpful to learn for the semantics of typed language.

field type: primitive type (int, varchar) (those are declared within hook_field_info())

field: encapsulated primitive type like :

struct fieldX {
int i;
struct *metadata_about_i; // like formatters and widgets
}
(lives in database only (not in-code) and exists after field_create_field() invocation)

field-instance: encapsulated type bound to a given entity and a given bundle like:

struct FieldInstanceX {
struct fieldX x;  // fieldX === field_name
char * (of entity name) e;
char * (of bundle name)  b;
}
(live in database only (not in-code) and exists after field_create_instance() invocation)

bundle: fieldable entity like:

struct bundleB {
  struct FieldInstanceX a; // FieldInstanceX
  struct FieldInstanceY b;
}

The most obvious sign of semantics inconsistencies is that field types are created with hook_info_field but listed with field_info_field_types.
While field_info_fields() list fields which have no corresponding hook because they don't leave in-code but are created once in an install file using field_create_field.
And the above applies to field's instances.

Taken from [1] in the $field description :

type (string) The type of the field, such as 'text' or 'image'. Field types are defined by modules that implement hook_field_info().

Search hook_field_info [2] for "type", "primitive", "data [type]", ... you won't find any of them.

On another side: field_info_bundles() list the bundles (optionally: of a given entity), so why not entity_bundles() or entity_list_bundles() ? [4]
As there's nothing related to fields here.
Moreover why not write "entity name" (KISS) instead of "entity type" which is something I can't even think about.

Note: I really can't understand why this Field API does not give place for fields to leave (also) in-code, IHMO that's the biggest pitfall of this API. ($field aims to setup much more useful, and mostly static, settings into $field from [1] than in the field type definition). There is even a hook for pseudo-fields (*_extra_fields)!

Note: there are inconsistencies in bool handling, no_ui, locked, translatable use either boolean or integer while, hopefully, the core often uses empty($val).

There should really exist one full documentation page per Drupal data semantic like: /doc/bundle: what it is, which API to call to show, list, add, delete, ...

[1] http://api.drupal.org/api/drupal/modules--field--field.module/group/field/7
[2] http://api.drupal.org/api/drupal/modules--field--field.api.php/function/...
[3] http://api.drupal.org/api/examples/field_example--field_example.module/f...
[4] http://api.drupal.org/api/drupal/modules--field--field.info.inc/function...

PS: which shorttag to link to a 7 API function ?

variable: int A; int is the variable type, A is the variable name.

entity: file entity: file is either the entity type or the entity name (machine name), but actually you'll
never write file entity A; so its unnecessary complexity to use type which imply that a the given entity is abstract
while in fact it is already a kind of implementation.

bundle: video bundle A; same as above,
video is an implementation, so its rather an bundle name rather than a bundle type.
It makes more sense to write:
fieldable file entity video; // video is the bundle machine-name
than
bundle video; // where video would be the bundle "type"

field: description or term reference are fields (let's forget about instance for now),
so "description" and "term reference" are field machine names.
But hook_field_info() implements the field type as in
text_field description;

So I still think that some of the current API semantics (and documentation) are inconsistent [3].
As a general documentation guideline, "machine name" should be used instead of "type" when possible.

But there is one sentence I disagree with you (and subsequently I disagree with [1]):

[...] bare minimum your module needs to implement a field

It would rather be defines a field type (what is highly bound to the storage backend).
So far in the whole example module there is one field implementation, it's there [2] because that's
the only data structure passed to the (only) call to field_create_field().

About the big picture understanding, a graph is still missing to me. Good documentation comes from good examples, API documentation and visualization (image) of relations when possible (especially when stuff becomes so complex).
About patch (or forgiveness) there exists 3) preliminary discuss about issues/features, especially since I'm new to Drupal I'm not reluctant to send patch but I obviously want to ensure they would solve an (existing) issue on which there's consensus.

[1] http://api.drupal.org/api/examples/field_example--field_example.module/g...
[2] http://api.drupal.org/api/examples/node_example--node_example.install/fu...
[3] PS: finally found #1374116: Move bundle CRUD API out of Field API and
#1380720: Rename various entity terms to be more intuitive where some part of the above comments should go.