Re: [boost] [Advice] Documenting the "refined by" relation for concepts

Subject: Re: [boost] [Advice] Documenting the "refined by" relation for concepts
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2015-06-14 12:28:34

Le 13/06/15 22:12, Louis Dionne a écrit :
> Dear all,
>
> When documenting a concept in a generic library, it is common to include what
> this concept is a "refinement of", i.e. which other concept(s) it specializes.
> For example, see the ForwardContainer concept from the SGI STL [1], which
> is a refinement of the Container concept.
>
> I find documenting this relation very useful. However, I have never seen the
> reverse relation of being "refined by" documented. It has been suggested to
> me [2] that Hana should document this "refined by" relation. Having never
> seen it done before, I'd like to know what the seasoned generic library
> writers think about it. The possibilities I personally see are
>
> 1. It's just not useful, and that's why it's not done
> 2. It's actually harmful, because you can't predict who is going to
>     refine a concept
> 3. There's no "logical" reason behind this, it just happened to work that
>     way in the SGI STL and everybody else followed that lead.
>
> Any input is appreciated.
>
>
Let me put the context. Hana Concepts as Haskell type classes list the 
type that an instance/model of the type class/concept.

E.g. in The Applicative Concept we see

"
Concrete models

Either, Lazy, Optional, Tuple
"

The refined by is no more than another case, that is not concrete but 
generic.

Let me put the context. Hana Concepts as Haskell type classes list the 
type that an instance/model of the type class/concept.

E.g. in The Applicative Concept we see
Concrete models

Either, Lazy, Optional, Tuple

The refined by is no more than another case, that is not concrete but 
generic. E.g. as we have

Applicative(T) => Monad(T) ....

Wouldn't be useful to add on the Applicative documentation that any 
concret model of Monad is a concrete model of Applicative.

My concern was about documenting these more generic cases as Hana has 
made the decision to document the models of relationship. Both will are 
subject to the same problems, this information can not be complete, but 
it can be for the types and concepts in Hana.

Another example that is not missing as Hana don't see Optional as a 
Monoid. Imagine that it was the case, and Hana contained a such a mapping.

I would find normal to find this in the Optional documentation on the 
section Modeled concepts

Monoid(T) => Monoid(Optional(T))

The question is if this should also appear as well a on the Monoid one.

Best,
Vicente

P.S. All this is no more than a cross reference between the Concepts and 
the models.
P.S.S. I recognize that maintaining this information manually is subject 
to errors, but I know that we are talking with experts that know how to 
generate these kind of cross reference information automatically ;-)