boostorg · mloskot · Sep 28, 2018 · Sep 27, 2018
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -20,6 +20,7 @@ please follow the workflow explained in this document.
   * [Using Boost.Build](#using-boostbuild)
   * [Using CMake](#using-cmake)
   * [Using Faber](#using-faber)
+* [Guidelines](#guidelines)
 
 ## Prerequisites
 
@@ -391,3 +392,41 @@ Here is an example of such lightweight workflow in Linux environment (Debian-bas
 Maintainer: [@stefanseefeld](https://github.com/stefanseefeld)
 
 _TODO_
+
+## Guidelines
+
+Boost.GIL is a more than a decade old mature library maintained by several
+developers with help from a couple of dozens contributors.
+It is important to maintain consistent design, look and feel.
+Thus, below a few basic guidelines are listed.
+
+First and foremost, make sure you are familiar with the official
+[Boost Library Requirements and Guidelines](https://www.boost.org/development/requirements.html).
+
+Second, strive for writing idiomatic C++11, clean and elegant code.
+
+**NOTE:** *The Boost.GIL source code does not necessary represent clean and elegant
+code to look up to. The library has recently entered the transition to C++11.
+Major refactoring overhaul is ongoing.*
+
+Maintain structure your source code files according to the following guidelines:
+
+* Name files in meaningful way.
+* Put copyright and license information in every file
+* If your changes [meet a certain threshold of originality](https://www.boost.org/users/license.html),
+  add yourself to the copyright notice. Do not put any additional authorship or
+  file comments (eg. no `\file` for Doxygen), revision information, etc.
+* In header, put `#include` guard based on header path and file name
+    ```
+    #ifndef BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP
+    #define BOOST_GIL_<DIR1>_<DIR2>_<FILE>_HPP
+    ...
+    #endif
+    ```
+* Make sure each [header is self-contained](https://github.com/boostorg/gil/wiki/Include-Directives-Order), i.e. that they include all headers they need.
+* All public headers should be placed in `boost/gil/` or `boost/gil/<component>/`.
+* All non-public headers should be placed `boost/gil/detail` or `boost/gil/<component>/detail`.
+* All public definitions should reside in scope of `namespace boost { namespace gil {...}}`.
+* All non-public definitions should reside in scope of `namespace boost { namespace gil { namespace detail {...}}}`.
+* Write your code to fit within **90** columns of text (see discussion on [preferred line length](https://lists.boost.org/boost-gil/2018/04/0028.php) in GIL).
+* Indent with **4 spaces**, not tabs. See the [.editorconfig](https://github.com/boostorg/gil/blob/develop/.editorconfig) file for details. Please, do not increases the indentation level within namespace.
diff --git a/doc/doxygen/tutorial.dox b/doc/doxygen/tutorial.dox
@@ -44,7 +44,7 @@ at http://stlab.adobe.com/gil
 The latest version of GIL can be downloaded from GIL's web page, at http://stlab.adobe.com/gil.
 GIL is approved for integration into Boost and in the future will be installed simply by installing Boost from http://www.boost.org. 
 GIL consists of header files only and does not require any libraries to link against. It does not require Boost to be built.
-Including \p boost/gil/gil_all.hpp will be sufficient for most projects.
+Including \p boost/gil.hpp will be sufficient for most projects.
 
 \section ExampleSec     Example - Computing the Image Gradient
 
@@ -63,7 +63,7 @@ Let us first start with 8-bit unsigned grayscale image as the input and 8-bit si
 Here is how the interface to our algorithm looks like:
 
 \code
-#include <boost/gil/gil_all.hpp>
+#include <boost/gil.hpp>
 using namespace boost::gil;
 
 void x_gradient(const gray8c_view_t& src, const gray8s_view_t& dst) {

diff --git a/example/affine.cpp b/example/affine.cpp
@@ -1,30 +1,17 @@
-/*
-    Copyright 2005-2007 Adobe Systems Incorporated
-
-    Use, modification and distribution are subject to 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).
-
-    See http://opensource.adobe.com/gil for most recent version including documentation.
-*/
-
-/*************************************************************************************************/
-
-///////////////////////
-////  NOTE: This sample file uses the numeric extension, which does not come with the Boost distribution.
-////  You may download it from http://opensource.adobe.com/gil
-///////////////////////
-
-/// \file
-/// \brief Test file for resample_pixels() in the numeric extension
-/// \author Lubomir Bourdev and Hailin Jin
-/// \date February 27, 2007
-
+//
+// Copyright 2005-2007 Adobe Systems Incorporated
+//
+// 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
+//
 #include <boost/gil.hpp>
 #include <boost/gil/extension/io/jpeg.hpp>
 #include <boost/gil/extension/numeric/sampler.hpp>
 #include <boost/gil/extension/numeric/resample.hpp>
 
+// Example for resample_pixels() in the numeric extension
+
 int main()
 {
     namespace gil = boost::gil;

diff --git a/example/convolution.cpp b/example/convolution.cpp
@@ -1,31 +1,17 @@
-/*
-    Copyright 2005-2007 Adobe Systems Incorporated
-
-    Use, modification and distribution are subject to 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).
-
-    See http://opensource.adobe.com/gil for most recent version including documentation.
-*/
-
-/*************************************************************************************************/
-
-///////////////////////
-////  NOTE: This sample file uses the numeric extension, which does not come with the Boost distribution.
-////  You may download it from http://opensource.adobe.com/gil 
-///////////////////////
-
-/// \file
-/// \brief Test file for convolve_rows() and convolve_cols() in the numeric extension
-/// \author Lubomir Bourdev and Hailin Jin
-/// \date February 27, 2007
-
+//
+// Copyright 2005-2007 Adobe Systems Incorporated
+//
+// 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
 #include <boost/gil/image.hpp>
 #include <boost/gil/typedefs.hpp>
 #include <boost/gil/extension/io/jpeg_io.hpp>
 #include <boost/gil/extension/numeric/kernel.hpp>
 #include <boost/gil/extension/numeric/convolve.hpp>
 
+// Example for convolve_rows() and convolve_cols() in the numeric extension
+
 int main() {
     using namespace boost::gil;
 

diff --git a/example/dynamic_image.cpp b/example/dynamic_image.cpp
@@ -1,20 +1,10 @@
-/*
-    Copyright 2005-2007 Adobe Systems Incorporated
-
-    Use, modification and distribution are subject to 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).
-
-    See http://opensource.adobe.com/gil for most recent version including documentation.
-*/
-
-/*************************************************************************************************/
-
-/// \file
-/// \brief Test file for using dynamic images
-/// \author Lubomir Bourdev and Hailin Jin
-/// \date February 27, 2007
-
+//
+// Copyright 2005-2007 Adobe Systems Incorporated
+//
+// 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
+//
 #include <boost/gil.hpp>
 #include <boost/gil/extension/dynamic_image/any_image.hpp>
 #include <boost/gil/extension/io/jpeg.hpp>

diff --git a/example/histogram.cpp b/example/histogram.cpp
@@ -1,25 +1,18 @@
-/*
-    Copyright 2005-2007 Adobe Systems Incorporated
-
-    Use, modification and distribution are subject to 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).
-
-    See http://opensource.adobe.com/gil for most recent version including documentation.
-*/
-
-/*************************************************************************************************/
-
-/// \file
-/// \brief Example file to demonstrate a way to compute histogram
-/// \author Lubomir Bourdev and Hailin Jin
-/// \date February 27, 2007
-
+//
+// Copyright 2005-2007 Adobe Systems Incorporated
+//
+// 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
+//
 #include <boost/gil.hpp>
 #include <boost/gil/extension/io/jpeg.hpp>
+
 #include <algorithm>
 #include <fstream>
 
+// Example file to demonstrate a way to compute histogram
+
 using namespace boost::gil;
 
 template <typename GrayView, typename R>

diff --git a/example/interleaved_ptr.cpp b/example/interleaved_ptr.cpp
@@ -1,27 +1,19 @@
-/*
-    Copyright 2005-2007 Adobe Systems Incorporated
-
-    Use, modification and distribution are subject to 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).
-
-    See http://opensource.adobe.com/gil for most recent version including documentation.
-*/
-
-/*************************************************************************************************/
-
-/// \file
-/// \brief Example file to demonstrate how to create a model of a pixel iterator
-/// \author Lubomir Bourdev and Hailin Jin
-/// \date February 27, 2007
-
+//
+// Copyright 2005-2007 Adobe Systems Incorporated
+//
+// 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
+//
 #ifdef WIN32
 #define _CRT_SECURE_NO_DEPRECATE 1
-#pragma warning(disable : 4244) // 
+#pragma warning(disable : 4244) //
 #pragma warning(disable : 4996) // MSFT declared it deprecated
 #endif
 
-// gcc doesn't compile unless we forward-declare at_c before we include gil...
+// Example file to demonstrate how to create a model of a pixel iterator
+
+// FIXME: Review and remove if possible: gcc doesn't compile unless we forward-declare at_c before we include gil...
 namespace boost { namespace gil {
     template <typename ChannelReference, typename Layout> struct interleaved_ref;
     template <typename ColorBase> struct element_reference_type;
@@ -31,8 +23,10 @@ namespace boost { namespace gil {
     at_c(const interleaved_ref<ChannelReference,Layout>& p);
 } }
 
-#include <iostream>
 #include <boost/gil/extension/io/jpeg_dynamic_io.hpp>
+
+#include <iostream>
+
 #include "interleaved_ptr.hpp"
 
 int main(int argc, unsigned char* argv[])

diff --git a/example/interleaved_ptr.hpp b/example/interleaved_ptr.hpp
@@ -1,48 +1,31 @@
-/*
-    Copyright 2005-2007 Adobe Systems Incorporated
-
-    Use, modification and distribution are subject to 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).
-
-    See http://opensource.adobe.com/gil for most recent version including documentation.
-*/
-
-/*************************************************************************************************/
-
-////////////////////////////////////////////////////////////////////////////////////////
-/// \file
-/// \brief Example on how to create a pixel iterator
-/// \author Lubomir Bourdev and Hailin Jin \n
-///         Adobe Systems Incorporated
-/// \date 2005-2007 \n Last updated on February 26, 2007
-///
-/// Definitions of standard GIL channel models
-///
-////////////////////////////////////////////////////////////////////////////////////////
-
-#ifndef GIL_INTERLEAVED_PTR_HPP
-#define GIL_INTERLEAVED_PTR_HPP
+//
+// Copyright 2005-2007 Adobe Systems Incorporated
+//
+// 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
+//
+#ifndef BOOST_GIL_EXAMPLE_INTERLEAVED_PTR_HPP
+#define BOOST_GIL_EXAMPLE_INTERLEAVED_PTR_HPP
 
 #include <boost/gil/pixel_iterator.hpp>
 #include "interleaved_ref.hpp"
 
+// Example on how to create a pixel iterator
+
 namespace boost { namespace gil {
-/////////////////////////////////////////////////////////////////////////
-///
-/// A model of an interleaved pixel iterator. Contains an iterator to the first channel of the current pixel
-///
-/// Models:
-///     MutablePixelIteratorConcept
-///        PixelIteratorConcept
-///           boost_concepts::RandomAccessTraversalConcept
-///           PixelBasedConcept
-///     HomogeneousPixelBasedConcept
-///        PixelBasedConcept
-///     ByteAdvanceableConcept
-///     HasDynamicXStepTypeConcept
-///
-/////////////////////////////////////////////////////////////////////////
+
+// A model of an interleaved pixel iterator. Contains an iterator to the first channel of the current pixel
+//
+// Models:
+//     MutablePixelIteratorConcept
+//        PixelIteratorConcept
+//           boost_concepts::RandomAccessTraversalConcept
+//           PixelBasedConcept
+//     HomogeneousPixelBasedConcept
+//        PixelBasedConcept
+//     ByteAdvanceableConcept
+//     HasDynamicXStepTypeConcept
 
 template <typename ChannelPtr,  // Models Channel Iterator (examples: unsigned char* or const unsigned char*)
           typename Layout>      // A layout (includes the color space and channel ordering)