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

Subject: Re: [boost] [Review:Contract] Some questions
From: Lorenzo Caminiti (lorcaminiti_at_[hidden])
Date: 2012-09-02 17:42:40

On Sun, Sep 2, 2012 at 2:25 PM, Vicente J. Botet Escriba
<vicente.botet_at_[hidden]> wrote:
> 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()

I don't think this last part can be done. In any case, we'd need a
more compliant Doxygen pp in order to support any of this... For
example, just try to #define macros to disable all contract in the
Doxyfile and then feed the code to Doxygen. In theory it should work
(because without contracts you just get plain C++03 declarations out
of the macro, essentially zero extra code) but Doxygen pp gets
confused already :(

>>>>>> = 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.

For now it's an only a way to interface with Boost.ConceptCheck. The
rest are future ideas (nothing is "half-implemented"). We started to
discuss static_assert and I'm happy to consider it... However, 3 will
require a lot of work (especially because there's no Boost.Generic
code to be found anywhere) and that's definitely future for a lib that
deals with contracts and not concepts after all. However, I personally
see no harm in leaving requires as is now so to check
Boost.ConceptCheck concepts.

Thanks,
--Lorenzo