search

boostorg / ptr_container

Boost.org ptr_container module
http://boost.org/libs/ptr_container
Boost Software License 1.0
13 stars 41 forks source link

Update docs for Boost 1.67 treatment of deprecated auto_ptr #17

Closed cstratopoulos closed 6 years ago

cstratopoulos commented 6 years ago

This PR is the documentation counterpart to https://github.com/boostorg/ptr_container/pull/8/ coded by @DanielaE.

For completeness sake, I'm going to rehash some points from the issue I opened (https://github.com/boostorg/ptr_container/issues/16) before starting this PR.

The main idea is that in the tradition of pseudo-types such as implementation-defined, hidden, void-or-deduced, etc., we introduce the type compatible-smart-ptr to be used as a stand-in for compile-time management of smart pointer interfaces. It should always appear in monospaced italics with a link back to an explanatory page, similar to e.g., this page from the Boost.Beast docs.

The central features of this PR, which can easily be previewed in browser, are

Due to limitations with reStructuredText, it is not directly possible to write italic monospaced hyperlinks. The result is that raw rst files (e.g., reversible_ptr_container) just have compatible-smart-ptr written. For all such pages the corresponding shell script used to generate HTML documentation has been updated to include an intermediate pipe to sed to add italics and a hyperlink (e.g., comp_rever_ptr_container.sh). This approach is a bit ugly but reading around online indicates that editing raw HTML is the most common way to work around this rst limitation. The old behavior of being able to generate documentation with sh comp_all.sh is unchanged.

Finally, I have edited tutorial_example.html to approximately reflect the raii_ptr alias introduced to tut1.cpp: https://github.com/cstratopoulos/ptr_container/blob/feature/auto_ptr-deprecate-doc-update/test/tut1.cpp#L144

danieljames commented 6 years ago

Is this intended for 1.67? If it is, it'll have to be merged soon.

eldiener commented 6 years ago

Let me look at this and then, if it is OK, I will merge the pull request and then merge to master.

danieljames commented 6 years ago

Thank you. I'd prefer to be able to check the develop branch documentation on the website first, which can take a few hours to update. So I might not update master until this evening.

eldiener commented 6 years ago

That is fine. Tell me when you want to merge these changes to master and I will do it, otherwise feel free to do it yourself when you are ready.

danieljames commented 6 years ago

Sorry I wasn't clear, the master branch isn't automatically updating, so I'll update it manually once I've checked the website updated okay. You can merge to master when you want,

eldiener commented 6 years ago

I merge the doc changes to the master branch. Thank you for doing this Christos and providing these documentation updates..

cstratopoulos commented 6 years ago

@eldiener happy to help! Will be near my computer pretty much all day today if any last minute fixes/typos pop up that I can help with.

danieljames commented 6 years ago

Thanks, everyone. The develop branch is up:

https://www.boost.org/doc/libs/develop/libs/ptr_container/doc/ptr_container.html

And I've updated master.

eldiener commented 6 years ago

Great ! Thanks Daniel !