Boost logo

Boost-Commit :

Date view Thread view Subject view Author view

Subject: [Boost-commit] svn:boost r85581 - in trunk/libs/sync: . doc
From: andrey.semashev_at_[hidden]
Date: 2013-09-05 15:56:47

Author: andysem
Date: 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013)
New Revision: 85581
URL: http://svn.boost.org/trac/boost/changeset/85581

Log:
Added a skeleton for docs with the notes for maintainers.

Added:
   trunk/libs/sync/
   trunk/libs/sync/doc/
   trunk/libs/sync/doc/Jamfile.v2 (contents, props changed)
   trunk/libs/sync/doc/changelog.qbk (contents, props changed)
   trunk/libs/sync/doc/gen_references.xsl (contents, props changed)
   trunk/libs/sync/doc/notes_for_maintainers.qbk (contents, props changed)
   trunk/libs/sync/doc/sync.qbk (contents, props changed)
   trunk/libs/sync/index.html (contents, props changed)

Added: trunk/libs/sync/doc/Jamfile.v2
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/sync/doc/Jamfile.v2 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013) (r85581)
@@ -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 =
+ <doxygen:param>RECURSIVE=YES
+ <doxygen:param>ALPHABETICAL_INDEX=YES
+ <doxygen:param>REPEAT_BRIEF=YES
+ <doxygen:param>ALWAYS_DETAILED_SEC=YES
+ <doxygen:param>BRIEF_MEMBER_DESC=NO
+ <doxygen:param>ABBREVIATE_BRIEF=YES
+ <doxygen:param>INHERIT_DOCS=YES
+ <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+ <doxygen:param>HIDE_UNDOC_CLASSES=YES
+ <doxygen:param>HIDE_SCOPE_NAMES=YES
+ <doxygen:param>EXTRACT_ALL=NO
+ <doxygen:param>EXTRACT_PRIVATE=NO
+ <doxygen:param>BUILTIN_STL_SUPPORT=YES
+ <doxygen:param>ENABLE_PREPROCESSING=YES
+ <doxygen:param>MACRO_EXPANSION=YES
+ <doxygen:param>TAB_SIZE=4
+ <doxygen:param>SOURCE_BROWSER=YES
+ <doxygen:param>VERBATIM_HEADERS=NO
+# <doxygen:param>SEARCH_INCLUDES=YES
+# <doxygen:param>"INCLUDE_PATH=../../.."
+# <doxygen:param>EXCLUDE_SYMBOLS="aux aux::*"
+ <doxygen:param>"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;\""
+ <xsl:param>boost.doxygen.detailns=detail
+# <xsl:param>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)
+ <xsl:param>"boost.doxygen.reftitle=Top level headers"
+ ;
+
+notfile top_level_refs : @gen-references : top_level_reference.xml ;
+
+doxygen locks_reference
+ :
+ $(locks_includes)
+ :
+ $(doxygen_params)
+ <xsl:param>"boost.doxygen.reftitle=Locks"
+ ;
+
+notfile locks_refs : @gen-references : locks_reference.xml ;
+
+doxygen support_reference
+ :
+ $(support_includes)
+ :
+ $(doxygen_params)
+ <xsl:param>"boost.doxygen.reftitle=Other libraries support layer"
+ ;
+
+notfile support_refs : @gen-references : support_reference.xml ;
+
+
+xml sync_doc
+ :
+ sync.qbk
+ :
+ <dependency>top_level_refs
+ <dependency>locks_refs
+ <dependency>support_refs
+ ;
+
+boostbook sync
+ :
+ sync_doc
+ :
+ <xsl:param>boost.root=../../../..
+ <xsl:param>boost.libraries=../../../libs/libraries.htm
+ <xsl:param>nav.layout=none
+ <xsl:param>boost.image=Boost
+ <xsl:param>navig.graphics=1
+ <xsl:param>chunk.section.depth=2
+ <xsl:param>boost.compact.function=0
+ <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/sync/doc/html
+ <format>pdf:<xsl:param>img.src.path=$(images_location)/
+ ;

Added: trunk/libs/sync/doc/changelog.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/sync/doc/changelog.qbk 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013) (r85581)
@@ -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]

Added: trunk/libs/sync/doc/gen_references.xsl
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/sync/doc/gen_references.xsl 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013) (r85581)
@@ -0,0 +1,79 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<!--
+ Copyright Andrey Semashev 2007 - 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 stylesheet extracts information about headers, classes, etc.
+ from the Doxygen-generated reference documentation and writes
+ it as QuickBook templates that refer to the according Reference sections.
+-->
+<xsl:transform version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+<xsl:output method="text"/>
+<xsl:template match="/library-reference">
+<xsl:text disable-output-escaping="yes">[/
+ 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!
+/]
+</xsl:text>
+<xsl:apply-templates>
+<xsl:with-param name="namespace"/>
+<xsl:with-param name="enclosing_namespace"/>
+</xsl:apply-templates>
+</xsl:template>
+
+<!-- Skip any text nodes -->
+<xsl:template match="text()"/>
+
+<!-- Headers -->
+<xsl:template match="header">
+<xsl:param name="namespace"/>
+<xsl:param name="enclosing_namespace"/>
+[template <xsl:value-of select="translate(@name, '/.', '__')"/>[][headerref <xsl:value-of select="@name"/>]]
+<xsl:apply-templates>
+<xsl:with-param name="namespace" select="$namespace"/>
+<xsl:with-param name="enclosing_namespace" select="$enclosing_namespace"/>
+</xsl:apply-templates>
+</xsl:template>
+
+<!-- Namespaces - only needed to construct fully qualified class names -->
+<xsl:template match="namespace">
+<xsl:param name="namespace"/>
+<xsl:param name="enclosing_namespace"/>
+<xsl:variable name="namespace_prefix">
+<xsl:value-of select="$namespace"/><xsl:if test="string-length($namespace) &gt; 0"><xsl:text>::</xsl:text></xsl:if>
+</xsl:variable>
+<xsl:apply-templates>
+<xsl:with-param name="namespace" select="concat($namespace_prefix, @name)"/>
+<xsl:with-param name="enclosing_namespace" select="@name"/>
+</xsl:apply-templates>
+</xsl:template>
+
+<!-- Classses -->
+<xsl:template match="class|struct">
+<xsl:param name="namespace"/>
+<xsl:param name="enclosing_namespace"/>
+[template <xsl:value-of select="concat('class_', $enclosing_namespace, '_', @name)"/>[][classref <xsl:value-of select="concat($namespace, '::', @name)"/><xsl:text> </xsl:text><xsl:value-of select="@name"/>]]
+<xsl:apply-templates>
+<xsl:with-param name="namespace" select="concat($namespace, '::', @name)"/>
+<xsl:with-param name="enclosing_namespace" select="concat($enclosing_namespace, '_', @name)"/>
+</xsl:apply-templates>
+</xsl:template>
+
+<!-- Free functions - currently disabled because multiple overloads generate duplicate QuickBook templates -->
+<!--
+<xsl:template match="function">
+<xsl:param name="namespace"/>
+<xsl:param name="enclosing_namespace"/>
+[template <xsl:value-of select="concat('func_', $enclosing_namespace, '_', @name)"/>[][funcref <xsl:value-of select="concat($namespace, '::', @name)"/><xsl:text> </xsl:text><xsl:value-of select="@name"/>]]
+</xsl:template>
+-->
+
+</xsl:transform>

Added: trunk/libs/sync/doc/notes_for_maintainers.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/sync/doc/notes_for_maintainers.qbk 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013) (r85581)
@@ -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]

Added: trunk/libs/sync/doc/sync.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/sync/doc/sync.qbk 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013) (r85581)
@@ -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] '''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[key]'''">#'''[key]'''</ulink>''']
+
+[/ 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]

Added: trunk/libs/sync/index.html
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/sync/index.html 2013-09-05 15:56:47 EDT (Thu, 05 Sep 2013) (r85581)
@@ -0,0 +1,15 @@
+<html>
+<head>
+<meta http-equiv="refresh" content="0; URL=doc/html/index.html">
+</head>
+<body>
+Automatic redirection failed, please go to
+doc/html/index.html &nbsp;<hr>
+<p>&copy; Copyright Andrey Semashev, 2013</p>
+<p>&copy; Copyright Vicente J. Botet Escriba, 2013</p>
+<p>&copy; Copyright Tim Blechmann, 2013</p>
+<p>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)</p>
+</body>
+</html>

Date view Thread view Subject view Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk