Documentation for extension development insufficient

[Phrogz]

Describe the bug The current document for writing a extensions are lacking key information:

• For each hook, what are the data types passed to the handler?
• For each hook, what is expected to be done by the handler?
  • Is the handler supposed to only read the information supplied?
  • Is the handler allowed to—or expected to—modify any of the passed data structures?
    • If so, in what way should they be modified? Removing data? Mutating? Adding?
• In what order are the hooks invoked, and what causes each to be invoked?
• How is an exporter expected to modify the final exported JSON?
  • By creating instances of existing glTF classes, or mutating existing classes, on the fly?
  • Somehow subclassing or overriding existing classes?
  • Waiting until gather_gltf_extensions_hook and modifying the glTF only then?
• Assuming a single add-on wants to round-trip their extension, how should the exporter and importer be structured?

Expected behavior The documentation and examples should clearly show a user how to do a concrete task. I'd suggest that in addition to the existing bare-bones, examples, a semi-real-world example is added, with both exporter and importer round-tripping the information.

[Phrogz]

In case it helps, I derived this hook order (which I think is correct) for the importer. I personally would have found something like this helpful for both import and export:

gather_import_gltf_before_hook
gather_import_scene_before_hook

for each node:
    gather_import_node_before_hook
    if node has a mesh:
        gather_import_mesh_before_hook
            gather_import_mesh_options
            for each primitive:
                gather_import_decode_primitive
            for each material:
                gather_import_material_before_hook
                gather_import_texture_before_hook
                gather_import_image_before_hook
                gather_import_image_after_hook
                gather_import_texture_after_hook
                gather_import_material_after_hook
        gather_import_mesh_after_hook

    else if it is a camera:
        gather_import_camera_before_hook
        gather_import_camera_after_hook

    else if it is a light:
        gather_import_light_before_hook
        gather_import_light_after_hook

    gather_import_node_after_hook

gather_import_scene_after_nodes_hook

gather_import_animations
for each animation:
    gather_import_animation_before_hook
    gather_import_animation_channel_before_hook
    gather_import_animation_channel_after_hook
    gather_import_animation_weight_before_hook
    gather_import_animation_weight_after_hook
    gather_import_animation_after_hook

gather_import_scene_after_animation_hook

[Phrogz]

I spent a few hours tracing the export hooks in order. This might be roughly correct:

gather_asset_hook

for each scene:
    vtree_before_filter_hook
    gather_tree_filter_tag_hook
    vtree_after_filter_hook

    for each node:
        if it is not a bone:
            gather_node_mesh_hook
            for each material:
                gather_attributes_change
                gather_image_hook
                gather_sampler_hook
                gather_texture_hook
                gather_texture_info_hook
                gather_material_pbr_metallic_roughness_hook
                gather_material_hook
                for each attribute:
                    gather_attribute_change
                gather_node_name_hook
                gather_node_hook
            gather_mesh_hook
        else:
            gather_joint_hook
        gather_node_name_hook
        gather_node_hook
    gather_scene_hook

    if Animation mode is "Actions" or "Active actions merged":
        for each exported node:
            pre_gather_actions_hook kinkangle
            gather_actions_hook kinkangle

        for each collected action:
            animation_switch_loop_hook(post=False)
            pre_animation_switch_hook
            post_animation_switch_hook

            if sample animations:
                for each channel:
                    switch on type:
                        gather_animation_object_sampled_channel_target_hook
                        gather_animation_bone_sampled_channel_target_hook
                    animation_gather_object_sampler
                    gather_animation_channel_hook
                animation_gather_object_channel
                animation_action_object_sampled
            else:
                animation_gather_fcurve_channel_target
                animation_gather_fcurve_channel_sampler
                animation_gather_fcurve_channel         # see issue #2351
                animation_gather_fcurve
            animation_switch_loop_hook(post=True)

    elsif mode is "Scene":
        ???
    elsif gathering as "NLA Tracks":
        ???

gather_gltf_hook
gather_gltf_extensions_hook
gather_gltf_encoded_hook

Not covered by the above are the following hooks that I didn't experience in my testing:

animation_action_sk_sampled
animation_action_sk_sampled_target
animation_gather_sk_channel
animation_gather_sk_channels
animation_track_switch_loop_hook
gather_animation_channel_target_hook
gather_attribute_keep
gather_camera_hook
gather_gltf_additional_textures_hook
gather_material_unlit_hook
gather_skin_hook
gather_tracks_hook
post_animation_track_switch_hook
pre_animation_track_switch_hook
pre_gather_tracks_hook