Re: [boost] [iterator] Regenerating the iterator docs

Subject: Re: [boost] [iterator] Regenerating the iterator docs
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2015-08-26 07:41:31

On 26.08.2015 14:17, Paul A. Bristow wrote:
>
>
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Andrey Semashev
>> Sent: 26 August 2015 12:07
>> To: boost_at_[hidden]
>> Subject: Re: [boost] [iterator] Regenerating the iterator docs
>>
>> On 26.08.2015 13:41, Paul A. Bristow wrote:
>>>> -----Original Message-----
>>>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
>>>> Edward Diener
>>>> Sent: 25 August 2015 18:01
>>>> To: boost_at_[hidden]
>>>> Subject: Re: [boost] [iterator] Regenerating the iterator docs
>>>>
>>>> On 8/25/2015 12:56 PM, Daniel James wrote:
>>>>> On 24 August 2015 at 19:06, Edward Diener <eldiener_at_[hidden]> wrote:
>>>>>> I have updated a very small portion of the iterator docs and now I
>>>>>> need to regenerate the documentation. Evidently despite iterator
>>>>>> having quickbook documentation the actual documentation presented
>>>>>> to end-users is created from RST files, python scripts, and make files.
>>>>>> But I do not see the process of regenerating the docs explained
>>>>>> anywhere so I am wondering if anyone knows how to do it.
>>>>>
>>>>> When I've changed them, I think I just used rst2html with the rst
>>>>> files that I updated.
>>>>
>>>> There is also a pdf version of the rst file that needs to be generated.
>>>
>>> A PDF version will come automatically from the Quickbook version -
>>> provided any additional info in the .rst is converted to doxygen-syntax comments.
>>>
>>> This is safe provided we assume that any inadvertent mistakes in this
>>> process will be caught by running the test suite. (If they are not,
>>> there is something wrong with the tests!)
>>
>> You mean there should be tests for the documentation?
>
> No - I only mean the normal tests in /test folder.
>
> Any edits to the include files carry a risk of 'collateral damage' from mistakes.
>
> It should not happen - but could.
>
> I am saying that repeating the normal tests should give sufficient assurance that this hasn't
> happened.
>
> And asking for confirmation that this is accepted by others.

I think adding Doxygen comments without changing the actual code is a 
pretty safe operation. Running tests afterwards would be a sufficient 
confirmation for me.