Re: [boost] [Review:Contract] Some questions

Subject: Re: [boost] [Review:Contract] Some questions
From: Vicente J. Botet Escriba (vicente.botet_at_[hidden])
Date: 2012-09-02 17:25:50

Le 02/09/12 22:33, Lorenzo Caminiti a écrit :
> On Sun, Sep 2, 2012 at 1:02 PM, Vicente J. Botet Escriba
> <vicente.botet_at_[hidden]> wrote:
>> Le 01/09/12 20:15, Lorenzo Caminiti a écrit :
>>
>>> On Sep 1, 2012 9:56 AM, "Vicente J. Botet Escriba"
>>> <vicente.botet_at_[hidden]>
>>> wrote:
>>>> Le 27/08/12 23:15, Vicente J. Botet Escriba a écrit :
>>>>
>>>>> = doxygen =
>>>>>
>>>>> BTW, have you tried to generate contract documentation using doxygen?
>>> Doxygen's preprocessor is too simple and it cannot correctly expand the
>>> macros. To generate Doxygen docs of code that contains the contract
>>> macros,
>>> you'd have to expand it before running Doxygen using you compiler -E or
>>> something like Wave so to feed Doxygen the code with the macros already
>>> expanded. You'd have to expand with all contracts disabled so Doxygen will
>>> see your normal code and generates docs for it.
>> NO This was not what I was expecting for doxygen ;-)
>>
>>> A different question (I'm not sure which one you intended to ask) is if my
>>> lib macros can automatically generate Doxygen's  @pre, @post, and @inv
>>> tags
>>> (they are named something like that).
>>
>> Yes, something like this is what I was requesting. I don't care about
>> whether the macros generate doxygen tags as @pre,@post and @inv. What I want
>> is an automatic generation for quickbook documents using doxygen.
>>
>>> An older rev used to do that--see
>>> release 0.3.469 in the Release Notes section (idea taken from [Tadin04],
>>> see Bibliography section and Features at bottom of Contract Programming
>>> Overview section). However, the Doxygen docs simply repeated the assertion
>>> code in the docs so it was more or less like looking at the contract code
>>> from the declarations (without the function definition code). Such
>>> automatically generated docs where of little value then the macros got too
>>> complex for the Doxygen pp anyway so this feature was abandoned.
>>
>> Are you saying that the user can look at the code as it describes clearly
>> the pre/post/inv and the documentation is not needed anymore?
>> Does you mean that people using your Contract library, and wanting an
>> hypertext documentation, will need to rewrite the pre/post/inv documentation
>> by hand if they want the information is on their hypertext docs?
> Wow, I can't believe I still have this code :) but here's an example
> of the Doxygen docs generated using the older library rev:
> http://contractpp.svn.sourceforge.net/viewvc/contractpp/releases/contractpp_0_2_190/doc/html/str/classstr.html
>
> Generated from this code:
> http://contractpp.svn.sourceforge.net/viewvc/contractpp/releases/contractpp_0_2_190/doc/html/Quick_Start.html#A_Complete_Example
Yeah, this is really great.
>
> I am saying that if you look at the
> Precondition/Postcondition/Invariant sections from the Doxygen link
> above they merely repeat the assertion code from the contracts you can
> read in the code itself. Therefore, this feature wasn't very useful to
> begin with then the macros became too complex for the Doxygen pp to
> expand them so this feature was removed.
>
> Is this the type of feature you are talking about? If not, could you
> provide an example of the code and ideal Doxygen docs generated? (Of
> course, you can write everything in just text format but just so I can
> see what would ideally be in the code and then in the automatically
> generated docs.)

Yes this is what I was looking for. It will yet better if

*Precondition:
   *{                 index >= 0 && index <self.size()/* "index in range" */;    }

could become

*Precondition:
   *index in range  : index >= 0 && index <self.size()

>
>>>>> = enable-if =
>>>>>
>>>>> Have you an example of the use of enable_if and contracts in the
>>> documentation?
>>>
>>> This should work as usual but I just realized I don't have an example for
>>> it. I'll test it and add an enable_if example.
>>>
>> I was wondering if the library should not use enable_if to emulate C++
>> proposed Concepts, as e.g. it seems Boost.Generic does. More I think on how
>> you are emulating C++ concepts, more I think that the emulation doesn't
>> corresponds to what a C++Concept user could expect. The use of
>> Boost.ConceptCheck doesn't seems to match the C++11 proposed Concept
>> semantics. I'm not saying that Boost.ConceptCheck is not useful, but the
>> semantic is different.
> I agree. However, I think this is more along the line of extending the
> lib to support concept definitions:
> http://contractpp.svn.sourceforge.net/viewvc/contractpp/releases/contractpp_0_4_1/doc/html/contract__/concepts.html#contract__.concepts.concept_definitions__not_implemented_
>
> Note that at the (very) end I could allow a few things all together in
> the requires statement:
> 1. Boost.ConceptCheck for backward compatibility (current).
> 2. static_assert (if we decide that using static assertions in just
> the concept declarations is not enough).
> 3. Boost.Generic-like concepts defined and checked using C++11
> expression SFINAE (future).
>
I think that this part (Concepts and the require clause) of the library 
is not enough mature and in order to avoid breaking changes in the 
future it should be removed now and added just once you have a  more 
sound solution.

Best,
Vicente