Documentation for Dict.__init__() constructor arguments is not clear

[ankostis]

Currently the documentation of the Dict.__init__() constructor explains its arguments with the following wording:

    trait : TraitType [ optional ]
        The type for restricting the contents of the Container. If
        unspecified, types are not checked.

    traits : Dictionary of trait types [optional]
        The type for restricting the content of the Dictionary for certain
        keys.

    default_value : SequenceType [ optional ]
        The default value for the Dict.  Must be dict, tuple, or None, and
        will be cast to a dict if not None. If `trait` is specified, the
        `default_value` must conform to the constraints it specifies.

From that, I cannot understand what is the trait and the traits keywords.

Particularly confusing is the term "Container"; a dict contains both keys and values.
Is one of the referring to the type of the dictionary keys and the other to the dictionary values?
Can it be improved to clarify this distinction? Or maybe add a usage example?

My apologies for this "support" thread,

[ankostis]

From the description I still cannot grasp what a "container" is, for a dict: is it's "values"?
Maybe the word container is not valid in this context, and write explicetely keys or values,.

Also it does not explain why "certain keys"?

So would you mean something like this (sorry, I'm still lost)?

    trait : TraitType [ optional ]
        The trait type restricting the Keys of the Dict container. 
        If unspecified, keys are not checked.

    traits : Dictionary of trait types [ optional ]
        A Python dictionary specifying the trait-types restricting 
        the Values for the matching keys in the Dict container.

[ankostis]

I'm always lost here :-(
My principal is that it is for the users to decide if a documentation text is adequate, isn't it?

[minrk]

Sorry, @ankostis! I'll take another swing at the docstring (#350). The dict is the container. The terminology comes from Python, where the base container types are dict, list, tuple, set. In this case, the contents of the container are its values. One thing that's definitely not clear yet: keys are never validated (hence #306), only values.

[ankostis]

Thanks for the tip on the "container" meaning!
My understanding problem was unsurmountablebecauseDictwas not inheritingContainer`.