[m-rev.] for post-commit review: more documentation for typeclass_infos in polymorphism_info.m

[Julien Fischer]

On Fri, 9 Oct 2026 at 19:43, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> Use more descriptive type names, and add documentation.

...

>
> diff --git a/compiler/polymorphism_info.m b/compiler/polymorphism_info.m
> index 4dbaac81d..a92080d3b 100644
> --- a/compiler/polymorphism_info.m
> +++ b/compiler/polymorphism_info.m
> @@ -50,32 +50,108 @@
>
>  :- func var_and_maybe_csa_to_var(var_and_maybe_csa) = prog_var.
>
> -%--------------------%
> +%---------------------%
>
> +    % These two types together describe a two-stage map from a type
> +    % to the type_info describing that type. The two stages specify
> +    %
> +    % - the type_ctor of the type, and
> +    % - its argument types.
> +    %
> +    % The type_info will in general be a heap cell consisting of
> +    %
> +    % - a pointer to the statically allocated type_ctor_info for
> +    %   the type_ctor (which will contain the arity, amongs other things), and

s/amongs/amongst/

> +    % - the type_info for each argument type.
> +    %
> +    % (The in-general part is there because for zero-arity type_ctors,
> +    % we do not allocate a heap cell.)
> +    %
> +    % The result of the two-stage map will be the program variable
> +    % holding the type_info, and, if the type contains no type variables,
> +    % then also a reference to the constant form of the type_info.
> +    %
>  :- type type_to_type_info_map ==
>      map(type_ctor, type_ctor_to_type_info_map).
>  :- type type_ctor_to_type_info_map ==
>      map(list(mer_type), var_and_maybe_csa).
>
> -:- type typeclass_info_map ==
> -    map(class_name, typeclass_info_class_map).
> -:- type typeclass_info_class_map ==
> -    map(list(mer_type), typeclass_info_map_entry).
> -:- type typeclass_info_map_entry
> -    --->    typeclass_info_map_entry(
> -                % The cons_id representing the base_typeclass_info.
> -                cons_id,
> +%---------------------%
>
> -                % Maps the arguments of the typeclass_info_cell_constructor
> -                % after the base_typeclass_info to the variable that holds the
> -                % typeclass_info for that cell.
> -                tci_args_map
> -            ).
> +    % These three types together describe a three-stage map from a typeclass
> +    % constraint to the to the typeclass_info describing that type.

Repeat of "to the".

s/type/constraint/

> +    % The first two stages specify
> +    %
> +    % - the class_id of the typeclass constraint, and
> +    % - its argument types.
> +    %
> +    % The third stage is needed because the general form of a typeclass_info
> +    % does NOT consist of just
> +    %
> +    % - a pointer to the statically allocated base_typeclass_info for
> +    %   the typeclass, and
> +    % - the type_info for each type,
> +    %
> +    % but also has two kinds of differences.
> +    %
> +    % The first difference is that a typeclass_info  also contains references
> +    % to other typeclass_infos (both from the context of the relevant
> +    % instance declaration, and for the applicable superclasses).
> +    %
> +    % Part of the second difference is that a typeclass_info contains
> +    % type_infos not for the argument types of the class, but for the types

not *only*

> +    % occurring in the instance declaration, which may be different.
> +    % The rest of the second difference is that the place of these type_infos
> +    % in the typeclass_info depends on whether the type variables that
> +    % they represent are constrained or not.
> +    %
> +    % This is why the third stage map specifies exactly the second-and-later
> +    % arguments of the typeclass_info_cell_constructor in a typeclass info cell
> +    % (the base_typeclass_info arg is always the first). In general, some
> +    % of these arguments will be type_infos, and some will be typeclass_infos.
> +    % Each argument may be a constant, or a variable.

That's looks fine otherwise.

Julien.