From e211ea428095dbdce7880973e8b56351a3ffb839 Mon Sep 17 00:00:00 2001 From: Andrey Semashev Date: Thu, 5 Sep 2013 19:56:47 +0000 Subject: [PATCH] Added a skeleton for docs with the notes for maintainers. [SVN r85581] --- doc/Jamfile.v2 | 153 ++++++++++++++++++++++++++++++++++ doc/changelog.qbk | 18 ++++ doc/gen_references.xsl | 79 ++++++++++++++++++ doc/notes_for_maintainers.qbk | 38 +++++++++ doc/sync.qbk | 92 ++++++++++++++++++++ index.html | 15 ++++ 6 files changed, 395 insertions(+) create mode 100644 doc/Jamfile.v2 create mode 100644 doc/changelog.qbk create mode 100644 doc/gen_references.xsl create mode 100644 doc/notes_for_maintainers.qbk create mode 100644 doc/sync.qbk create mode 100644 index.html diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100644 index 0000000..9827513 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,153 @@ +# +# Copyright Andrey Semashev 2013. +# Distributed under the Boost Software License, Version 1.0. +# (See accompanying file LICENSE_1_0.txt or copy at +# http://www.boost.org/LICENSE_1_0.txt) +# + +using quickbook ; +using boostbook ; +using doxygen ; +using xsltproc ; + +import set ; +import doxygen ; +import xsltproc ; +import notfile ; +import path ; + +project boost/libs/sync/doc ; + +path-constant images_location : html ; + +# NOTE: At least Doxygen 1.8.2 is needed to generate docs correctly. Older versions don't support C++11 constructs correctly and generate misleading docs. +local doxygen_params = + RECURSIVE=YES + ALPHABETICAL_INDEX=YES + REPEAT_BRIEF=YES + ALWAYS_DETAILED_SEC=YES + BRIEF_MEMBER_DESC=NO + ABBREVIATE_BRIEF=YES + INHERIT_DOCS=YES + HIDE_UNDOC_MEMBERS=YES + HIDE_UNDOC_CLASSES=YES + HIDE_SCOPE_NAMES=YES + EXTRACT_ALL=NO + EXTRACT_PRIVATE=NO + BUILTIN_STL_SUPPORT=YES + ENABLE_PREPROCESSING=YES + MACRO_EXPANSION=YES + TAB_SIZE=4 + SOURCE_BROWSER=YES + VERBATIM_HEADERS=NO +# SEARCH_INCLUDES=YES +# "INCLUDE_PATH=../../.." +# EXCLUDE_SYMBOLS="aux aux::*" + "PREDEFINED=BOOST_SYNC_DETAIL_DOXYGEN \\ + BOOST_SYMBOL_VISIBLE= \\ + BOOST_FORCEINLINE=inline \\ + BOOST_STATIC_ASSERT(x)= \\ + BOOST_STATIC_ASSERT_MSG(x,y)= \\ + BOOST_RV_REF(x)=\"x&&\" \\ + BOOST_NESTED_TEMPLATE=template \\ + BOOST_CONSTEXPR=constexpr \\ + BOOST_CONSTEXPR_OR_CONST=constexpr \\ + BOOST_NOEXCEPT=noexcept \\ + BOOST_NOEXCEPT_IF(x)=noexcept(x) \\ + BOOST_NOEXCEPT_OR_NOTHROW=noexcept \\ + BOOST_COPY_ASSIGN_REF(x)=\"x const&\" \\ + BOOST_APPEND_EXPLICIT_TEMPLATE_TYPE(x)= \\ + BOOST_DEFAULTED_FUNCTION(x,y)=\"x = default;\" \\ + BOOST_DELETED_FUNCTION(x)=\"x = delete;\" \\ + BOOST_EXPLICIT_OPERATOR_BOOL()=\"explicit operator bool() const;\"" + boost.doxygen.detailns=detail +# boost.doxygen.detail=implementation_ + ; + + +local top_level_includes = + [ glob + ../../../boost/sync/*.hpp + ] ; + +local locks_includes = + [ glob + ../../../boost/sync/locks/*.hpp + ] ; + +local support_includes = + [ glob + ../../../boost/sync/support/*.hpp + ] ; + + +# This rule generates *.qbk files with macros with references to files, classes, etc. from the doxygen resulting *.xml files. +rule gen-references ( target : source : properties * ) +{ + DEPENDS target : source ; + local source-path = [ path.make [ on $(source) return $(LOCATE) ] ] ; + STYLESHEET on $(target) = [ path.native [ path.join $(source-path) gen_references.xsl ] ] ; + local target-name = $(source:B) ; + TARGET on $(target) = [ path.native [ path.join $(source-path) $(target-name:S=.qbk) ] ] ; +} +actions gen-references +{ +# echo "*** Executing " $(NAME:E=xsltproc) -o "$(TARGET)" "$(STYLESHEET)" "$(>)" + $(NAME:E=xsltproc) -o "$(TARGET)" "$(STYLESHEET)" "$(>)" +} + + +doxygen top_level_reference + : + $(top_level_includes) + : + $(doxygen_params) + "boost.doxygen.reftitle=Top level headers" + ; + +notfile top_level_refs : @gen-references : top_level_reference.xml ; + +doxygen locks_reference + : + $(locks_includes) + : + $(doxygen_params) + "boost.doxygen.reftitle=Locks" + ; + +notfile locks_refs : @gen-references : locks_reference.xml ; + +doxygen support_reference + : + $(support_includes) + : + $(doxygen_params) + "boost.doxygen.reftitle=Other libraries support layer" + ; + +notfile support_refs : @gen-references : support_reference.xml ; + + +xml sync_doc + : + sync.qbk + : + top_level_refs + locks_refs + support_refs + ; + +boostbook sync + : + sync_doc + : + boost.root=../../../.. + boost.libraries=../../../libs/libraries.htm + nav.layout=none + boost.image=Boost + navig.graphics=1 + chunk.section.depth=2 + boost.compact.function=0 + pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/sync/doc/html + pdf:img.src.path=$(images_location)/ + ; diff --git a/doc/changelog.qbk b/doc/changelog.qbk new file mode 100644 index 0000000..5edceda --- /dev/null +++ b/doc/changelog.qbk @@ -0,0 +1,18 @@ +[/ + Copyright Vicente J. Botet Escriba 2013. + Copyright Andrey Semashev 2013. + Copyright Tim Blechmann 2013. + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) + + This document is a part of Boost.Sync library documentation. +/] + +[section:changelog Changelog] + +[heading 1.0, Boost 1.55] + +This is the first release of the library since extraction from __boost_thread__. + +[endsect] diff --git a/doc/gen_references.xsl b/doc/gen_references.xsl new file mode 100644 index 0000000..db19e02 --- /dev/null +++ b/doc/gen_references.xsl @@ -0,0 +1,79 @@ + + + + + +[/ + Copyright Andrey Semashev 2013. + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) + + This document is a part of Boost.Sync library documentation. + + This document was automatically generated, DO NOT EDIT! +/] + + + + + + + + + + + + + + +[template [][headerref ]] + + + + + + + + + + + +:: + + + + + + + + + + + +[template [][classref ]] + + + + + + + + + + diff --git a/doc/notes_for_maintainers.qbk b/doc/notes_for_maintainers.qbk new file mode 100644 index 0000000..387f5d3 --- /dev/null +++ b/doc/notes_for_maintainers.qbk @@ -0,0 +1,38 @@ +[/ + Copyright Vicente J. Botet Escriba 2013. + Copyright Andrey Semashev 2013. + Copyright Tim Blechmann 2013. + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + http://www.boost.org/LICENSE_1_0.txt) + + This document is a part of Boost.Sync library documentation. +/] + +[section:notes_for_maintainers Notes for maintainers] + +This library is maintained by several developers, and in order it to have a consistent design, look and feel, a few guidelines need to be followed: + +[heading Code formatting and indentation] + +* The code is indented with spaces, 4 spaces per tab. +* Namespace braces on the same line, all other braces - on the next line, with the same indent. At the closing brace for a namespace, there is a comment with the namespace name. +* Namespaces don't increase the level of indentation. In all other cases braces increase the level of indentation. +* Member/base initialization list for constructors on the same line, if it's small (1-2 members) or 1 member/base per line. Colon is left on the signature line. +* No leading commas (i.e. if on multiple lines, initialization list and arguments have commas at the end of line, not at the beginning). + +[heading Naming conventions] + +* Data member names start with m_, unless the enclosing struct only has public data members (i.e. the intention of the struct is to enclose some data with no further logic). +* Template parameters are named in CamelCase, other symbol names follow C++ style (lower-case, with underscores). +* All non-public headers should be placed into `sync/detail` directory. All non-public names should reside in the `sync::detail` namespace. All non-public macro names should start with `BOOST_SYNC_DETAIL_`. +* All public names should reside in the `sync` namespace. Nested namespaces are also possible. All public macro names should start with `BOOST_SYNC_`. User-definable config macros should start with `BOOST_SYNC_WITH_`, `BOOST_SYNC_WITHOUT_` (for component selection, if any), `BOOST_SYNC_USE_` or `BOOST_SYNC_NO_`. This does not include macros the library defines itself as a result of various compatibility checks (these count as non-public ones). + +[heading Code structure] + +* Every header includes `boost/sync/detail/config.hpp`. The config header contains all configuration macros, but no auto-linking code. If the built library appears, the auto-linking machinery and macros will be in a separate header, which will be included only by those components that need it. +* Every header includes `boost/sync/detail/header.hpp` before any code (as the last include) and `boost/sync/detail/footer.hpp` after all code. These two files are for warning and ABI management. +* All move semantics is implemented through __boost_move__. +* All platform-specific code that depends on library configuration and can have different ABIs should be enclosed in a nested inline namespace that corresponds to the configuration. This gives a basic protection from the library misconfiguration in the user's application. + +[endsect] diff --git a/doc/sync.qbk b/doc/sync.qbk new file mode 100644 index 0000000..24ef7a9 --- /dev/null +++ b/doc/sync.qbk @@ -0,0 +1,92 @@ +[library Boost.Sync + [quickbook 1.5] + [version v1] + [authors [Botet Escriba, Vicente J.], [Semashev, Andrey], [Blechmann, Tim]] + [copyright 2013 Vicente J. Botet Escriba] + [copyright 2013 Andrey Semashev] + [copyright 2013 Tim Blechmann] + [license + Distributed under the Boost Software License, Version 1.0. + (See accompanying file LICENSE_1_0.txt or copy at + [@http://www.boost.org/LICENSE_1_0.txt]). + ] + [id sync] + [source-mode c++] + [last-revision $Date: 2013-05-18 00:11:22 +0400 (Sat, 18 May 2013) $] +] + +[c++] + +[/ Links to external resources /] +[def __boost_config__ [@http://www.boost.org/doc/libs/release/libs/config/doc/html/index.html Boost.Config]] +[def __boost_smart_ptr__ [@http://www.boost.org/doc/libs/release/libs/smart_ptr/smart_ptr.htm Boost.SmartPtr]] +[def __boost_function__ [@http://www.boost.org/doc/libs/release/doc/html/function.html Boost.Function]] +[def __boost_system__ [@http://www.boost.org/doc/libs/release/libs/system/doc/index.html Boost.System]] +[def __boost_date_time__ [@http://www.boost.org/doc/libs/release/doc/html/date_time.html Boost.DateTime]] +[def __boost_thread__ [@http://www.boost.org/doc/libs/release/doc/html/thread.html Boost.Thread]] +[def __boost_preprocessor__ [@http://www.boost.org/doc/libs/release/libs/preprocessor/doc/index.html Boost.Preprocessor]] +[def __boost_bind__ [@http://www.boost.org/doc/libs/release/libs/bind/bind.html Boost.Bind]] +[def __boost_lambda__ [@http://www.boost.org/doc/libs/release/doc/html/lambda.html Boost.Lambda]] +[def __boost_phoenix__ [@http://www.boost.org/doc/libs/release/libs/phoenix/doc/html/index.html Boost.Phoenix]] +[def __boost_optional__ [@http://www.boost.org/doc/libs/release/libs/optional/index.html Boost.Optional]] +[def __boost_mpl__ [@http://www.boost.org/doc/libs/release/libs/mpl/doc/index.html Boost.MPL]] +[def __boost_exception__ [@http://www.boost.org/doc/libs/release/libs/exception/doc/boost-exception.html Boost.Exception]] +[def __boost_asio__ [@http://www.boost.org/doc/libs/release/doc/html/boost_asio.html Boost.ASIO]] +[def __boost_move__ [@http://www.boost.org/doc/libs/release/doc/html/move.html Boost.Move]] +[def __boost_utility__ [@http://www.boost.org/doc/libs/release/libs/utility/utility.htm Boost.Utility]] +[def __boost_quickbook__ [@http://www.boost.org/doc/libs/release/doc/html/quickbook.html Boost.Quickbook]] + +[template ticket[key] '''#'''[key]''''''] + +[/ Auto-generated macros that refer to Reference sections /] +[include top_level_reference.qbk] +[include locks_reference.qbk] +[include support_reference.qbk] + + +[section:installation Installation and compatibility] + +[section:supported_compilers Supported compilers and platforms] + +The library should build and work with a reasonably compliant compiler. The library was successfully built and tested on the following platforms: + +* Windows XP, Windows Vista, Windows 7. MSVC 8.0 SP1, MSVC 9.0 and newer. +* Linux. GCC 4.5 and newer. Older versions may work too, but it was not tested. +* Linux. Intel C++ 13.1.0.146 Build 20130121. +* Linux. Clang 3.2. + +The following compilers/platforms are not supported and will likely fail to compile the library: + +* C++11 compilers with non-C++11 standard libraries (like Clang with libstdc++ from GCC 4.2). Please, use a C++11 standard library in C++11 mode. +* MSVC 8.0 (without SP1) and older. +* GCC 4.0 and older. +* Borland C++ 5.5.1 (free version). Newer versions might or might not work. +* Windows 9x, ME, NT4 and older are not supported. + +Boost.Log should be compatible with all hardware architectures supported by Boost. However, in case of 32 bit x86 architecture the library requires at least i586 class CPU to run. + +[endsect] + +[section:config Configuring and building the library] + +[endsect] + +[endsect] + +[include:sync notes_for_maintainers.qbk] + +[section:reference Reference] + +[xinclude top_level_reference.xml] +[xinclude locks_reference.xml] +[xinclude support_reference.xml] + +[endsect] + +[include:sync changelog.qbk] + +[section:acknowledgments Acknowledgments] + +* This library originates from __boost_thread__ which was originally developed by Anthony Williams and later maintained by Vicente J. Botet Escriba. Many design choices of this library were originally made by __boost_thread__ developers. + +[endsect] diff --git a/index.html b/index.html new file mode 100644 index 0000000..1a020e1 --- /dev/null +++ b/index.html @@ -0,0 +1,15 @@ + + + + + +Automatic redirection failed, please go to +doc/html/index.html  
+

© Copyright Andrey Semashev, 2013

+

© Copyright Vicente J. Botet Escriba, 2013

+

© Copyright Tim Blechmann, 2013

+

Distributed under the Boost Software License, Version 1.0. (See accompanying +file LICENSE_1_0.txt or copy +at www.boost.org/LICENSE_1_0.txt)

+ +