boost_mirror/geometry
1
0
Fork 0
mirror of https://github.com/boostorg/geometry.git synced 2025-05-10 07:34:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1089 from vissarion/fix/doc_tutorials

Browse Source 
Fix/doc tutorials
This commit is contained in:
Vissarion Fisikopoulos 2022-12-01 11:06:14 +02:00 committed by GitHub
commit b81e82b0f2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 17 additions and 354 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
CONTRIBUTING.md Normal file
View File

@ -0,0 +1,14 @@
# Contributing to Boost.Geometry
Boost.Geometry is a member of [Boost](https://www.boost.org) libraries.
## Table of Contents
* [**Contribution Tutorial**](http://github.com/boostorg/geometry/wiki/Contribution-Tutorial)
* [**Guidelines for Developers**](http://github.com/boostorg/geometry/wiki/Guidelines-for-Developers)
* [**Generating and Improving Documentation**](https://github.com/boostorg/geometry/wiki/Generating-and-Improving-Documentation)
### Resources
* [**Debugging**](http://github.com/boostorg/geometry/wiki/Debugging)
* [**Talks**](http://github.com/boostorg/geometry/wiki/Talks)

116
doc/about_documentation.qbk
View File

@ -1,116 +0,0 @@
[/============================================================================
Boost.Geometry (aka GGL, Generic Geometry Library)
Copyright (c) 2009-2012 Barend Gehrels, Amsterdam, the Netherlands.
Copyright (c) 2009-2012 Mateusz Loskot, London, UK.
Copyright (c) 2009-2012 Bruno Lalande, Paris, France.
Use, modification and distribution is 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)
=============================================================================/]
[section:aboutdoc About this Documentation]
Within the Boost community there are several styles of documenting. Most libraries nowadays are using QuickBook, the WikiWiki style documentation.
Boost.Geometry started with Doxygen, and during review it was decided to go to QuickBook. However, it was convenient to keep Doxygen also there: it does a good job of connecting descriptions to function and class declarations.
Doxygen is able to generate XML (besides the normal HTML output), containing all documentation.
So the challenge was to translate the XML generated by doxygen to QuickBook. At least, translate parts of it. Boost contains currently two tools using XSLT to go from Doxygen-XML to BoostBook, or to QuickBook. These tools are used within Boost.Random and Boost.Asio (and maybe more). However, this XSLT process was quite hard, did not deliver (yet) the wished results, and we are all C++ programmers. So another tool was born, this time in C++ using RapidXML, going from Doxygen-XML to QuickBook with the ability to mix both.
[heading The chain]
The process is as following:
# call doxygen to go from C++ to XML
# call ['doxygen_xml2qbk] to go from XML to QuickBook
# call bjam to from QuickBook to HTML
# bjam translates QuickBook to BoostBook
# bjam then translates from BoostBook to DocBook
# bjam then translates from DocBook to HTML
This chain is currently called by "make_qbk.py", a Python script which calls the chain above in the right order. Python ensures that the chain can be handled in both Windows and Linux environments (it is probably possible to call all parts with bjam too).
[heading The reference matrix]
There reference matrix is the only thing written in BoostBook. It is an XML file with an overview of all Boost.Geometry functionality. Presenting it like this is not possible within QuickBook, therefore BoostBook XML is used here. It is included by the QuickBook code. The Boost.Asio documentation contains a similar reference matrix.
[heading Mixing QuickBook into C++ code]
With Doxygen it is possible to define aliases. Specificly for ['doxygen_xml2qbk], the alias [*\qbk{...}] was defined. This alias [*\qbk{...}] add some XML-tags around the text inside the alias, such that that included part is recognizable by the converter.
So the C++ code might look like this:
[pre
/*!
\brief Some explanation
\ingroup some_group
\details Some details
\tparam Geometry Description of the template parameter
\param geometry Description of the variable
\qbk{ \[include reference/more_documentation.qbk\] }
*/
]
First you see normal Doxygen comments. The last line uses the alias \qbk{...} to include a QuickBook file. So most of the documentation can be written in that QuickBook file: behaviour, complexity, examples, related pages, etc.
In the example above a QuickBook include statement is used. But any QuickBook code can be used, the QuickBook code does not have to be stored in a separate file. Two more samples:
[pre
/*!
...
\qbk{
\[heading Example\]
\[area_with_strategy\]
\[area_with_strategy_output\]
\[heading Available Strategies\]
\[link geometry.reference.strategies.strategy_area_cartesian Cartesian\]
}
*/
]
In this example pieces of QuickBook are included, two headers, two examples (this is the QuickBook way - the examples are defined elsewhere), and a link.
[heading QuickBook within C++ issues]
There are two issues: the comma and the asterisk. If within the [*\qbk] alias a comma is used, it is recognized by Doxygen as another parameter, and therefore will not deliver the correct results, or result into errors. This is easily solvable by escaping comma's (by putting a backslash directly before the comma, \\, ). It within the [*\qbk] alias an asterisk is used on the first line, it is interpreted by Doxygen as well. This asterisk can be escaped as well, and this time it is ['doxygen_qbk2xml] which handles this escape and translates it back into an asterisk.
[heading Overloads]
Boost.Geometry contains a lot of overloads, two functions with the same name and, for example, a different number of parameters. Or, as another example, a const and a non-const version. They can be marked specificly to the ['doxygen_xml2qbk] tool with the \qbk alias, by adding a specific description for the overload. So, for example, [*\qbk{distinguish,with strategy}] will result in another page where the text "with strategy" is added, and it is processed as "_with_strategy" within the QuickBook section name.
[heading Overloads and sharing documentation]
With overloads, part of the documentation must be shared, and other part must not. The descriptions are often the same. But the examples are usually not. So it is a balance between sharing documentation, including shared documentation, avoiding too much separate QuickBook files containing pieces of documentation and avoiding including too much QuickBook code within the C++ code...
[heading Doxygen aliases]
While documenting a large library, it is unavoidable that you have to document the same parameters in different places. For example, the template parameter [*Geometry], and the variable [*geometry], occur at least 100 times in our library.
To avoid repeating the same text again and again, Doxygen aliases are used. So \tparam_geometry means that the generic description for a template parameter geometry is inserted. \param_geometry does the same for a parameter. This is all handled by Doxygen itself. The aliases can also be parameterized, for example: [*\return_calc{area}] is expanded to: ['The calculated area]
This is for Doxygen alone and is not related to ['doxygen_xml2qbk] or QuickBook.
[heading QuickBook macros]
QuickBook has the same functionality for the same purpose: macro's or templates can be defined. Within Boost.Geometry this is used in the QuickBook parts of the documentation. So the general rule would be: where it is possible to use a Doxygen alias, we use a Doxygen alias. If we are outside the scope of Doxygen and we want to define a macro, we use a QuickBook macro.
Stated otherwise, we don't use the generated Doxygen documentation, but if we would, it would look correct and would not be unreadable by unexpanded QuickBook macro's.
[heading Code examples]
We favour the use of code examples within the generated documentation. Example code must be correct, so examples must compile, run, and produce the correct results. QuickBook has a nice solution to include and present C++ source code, including syntax highlighting. So we generally present the example (a complete example including necessary headerfiles) and the output. Asserts are not used here, these are examples and no tests.
So this is why we did enclose in the \qbk alias above:
[pre
\[heading Example\]
\[area_with_strategy\]
\[area_with_strategy_output\]
]
We define a heading, we include the example (here denoted by the name "area_with_strategy") and we include the output of the sample "area_with_strategy_output". Note that we simulate that the output is C++ code, a trick giving the appropriate formatting (there might be other ways to get the same effect).
All these QuickBook examples are included in the doc\/src\/examples\/* folders, where also a Jamfile is present. Running bjam there ensures that nothing is broken in the examples.
Some examples, if relevant, are accompagnied by images. The images are generated by the example themselves (though marked as commented out for QuickBook), deliver an SVG file which can be manually converted to a PNG (I'm using InkScape for that which is quite convenient).
[endsect]

3
doc/geometry.qbk
View File

@ -145,7 +145,4 @@ Boost.Geometry contains contributions by:
[endsect] [endsect]
[include release_notes.qbk] [include release_notes.qbk]
[/ TODO: [include guidelines.qbk] /]
[include about_documentation.qbk]
[include acknowledgments.qbk] [include acknowledgments.qbk]

232
doc/guidelines.qbk
View File

@ -1,232 +0,0 @@
[/============================================================================
Boost.Geometry (aka GGL, Generic Geometry Library)
Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands.
Copyright (c) 2008-2012 Bruno Lalande, Paris, France.
Copyright (c) 2009-2013 Mateusz Loskot, London, UK.
Use, modification and distribution is 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)
=============================================================================/]
[section:guidelines Guidelines for developers]
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.
Rules of [@boost:/development/requirements.html Boost Library Requirements and Guidelines]
and [@boost:/development/header.html Boost Header Policy] always have highest authority.
Generally, prefer style of modern C++, conventions as used in latest C++ standard
document and C++ Standard Library. Boost.Spirit is a good example of
how to write and format high quality C++ code.
Some guidelines specific to Boost.Geometry library are outlined below.
[heading Code structure]
* Every file shall have header with copyright and license information.
* Do not put any history or revision information in comments in source files.
Log it with VCS used in the Boost project.
* Every header shall have `#include` guard based on header path and file name:
``
#ifndef BOOST_GEOMETRY_<DIR1>_<DIR2>_<FILE>_HPP
#define BOOST_GEOMETRY_<DIR1>_<DIR2>_<FILE>_HPP
...
#endif // BOOST_GEOMETRY_<DIR1>_<DIR2>_<FILE>_HPP
``
* `#include` directives shall be ordered according the most authoritative header:
* C Standard Library (using C++ library names, i.e. `<cstdlib>`)
* C++ Standard Library
* Boost C++ Libraries
* Boost.Geometry headers
* Other 3rd-party headers (only if applicable! in some samples only)
* Header within these sections should be ordered alphabetically, especially if there are many of them included.
* Namespaces don't increase the level of indentation.
In all other cases braces increase the level of indentation.
``
namespace boost { namespace geometry
{
namespace mynewspace
{
template <typename Point>
struct my_new_model
{
typedef point_type;
}
} // namespace mynewspace
}} // namespace boost::geometry
``
* Namespace closing brace should have comment with the namespace name.
* All non-public headers should be placed into `boost/geometry/detail` or
`boost/geometry/*/detail` directory, depending on component level.
* All non-public names should reside in the `boost::geometry::detail` or
`boost::geometry::*::detail` namespace, depending on component level.
* All traits should be placed in dedicated `boost::geometry::traits` or
`boost::geometry::*::traits` namespace
* All tag dispatching routines should be placed in dedicated
`boost::geometry::*::dispatch` namespace.
* Access specifiers for class members shall be orderd as public first, then protected and private at the bottom.
The public members define class interface, thus they are of the highest interested for users, so show them first.
* Exceptions to this rule are allowed for typedef aliases required to be defined first.
[heading Code formatting and indentation]
* The code is indented with spaces, 4 spaces per tab.
* The preferred line length is 80 characters, with maximum length of 100.
* The limit is relaxed for very long string literals (e.g. Well-Known Text with data used in tests and examples).
* Member/base initialization list for constructors on the same line,
if it's small (1-2 members) or 1 member/base per line with leading comma on the left:
```
struct T
{
T(int a, int b)
: a(a)
, b(b)
{}
int a;
int b;
};
```
* Template declaration with long template parameter list shall be formatted
with one template parameter per line, all parameters indented,
but `<` and `>` brackets not indented:
```
template
<
typename T,
typename P,
typename C = std::vector<Point>
>
struct polygon
{
typedef typename boost::remove_const
<
typename traits::point_type<T>::type
>::type type
};
```
* References and pointers should be formatted emphasizing type, not syntax:
```
T const& t;
T* t;
T* const t;
T const* t;
T const* const t;
```
* Braces enclosing block of code (if-else, loops) should be placed in separate lines
```
if (expr)
{
}
```
* Parentheses around expressions should not be pre/post-fixed with spaces.
[heading Naming conventions]
* All names follow style of the C++ Standard, lowercase with words separated with underscore `_`,
unless otherwise specified (see other rules).
* Template parameters are named in CamelCase.
* Concepts are named in CamelCase.
* Name of a class data member shall start with `m_` prefix.
The Boost sample header gives no prefix or suffix at all.
However, the `m_` prefix is used in some (not many) Boost libraries as well (e.g. math/tools/remez).
* All macro names shall be in upper-case, words separated with underscore `_`.
* All macro names shall start with `BOOST_GEOMETRY_`.
* All non-public macro names should start with `BOOST_GEOMETRY_DETAIL_` (not used often yet, if at all).
* All public names should reside in the `boost::geometry` namespace.
Nested namespaces are also possible.
* Avoid cryptic names and abbreviations for elements used in wider context (e.g. types, functions).
Short names are allowed if context of use is local, narrow and easily tracable
For example, use of `it` for `iterator` in body of a loop in function:
```
template <typename Range, typename Functor>
static inline void apply(Range& range, Functor& f)
{
for (typename boost::range_iterator<Range>::type it = boost::begin(range);
it != boost::end(range); ++it)
{
f(*it);
}
}
```
[heading C++ use conventions]
* Keyword struct is preferred either for POD structures, or for classes used at compile-time
like metafunctions, tags, traits, etc.
* Keyword class is preferred for classes meant to produce actual objects, which have methods
and an active role in the runtime functioning of the program.
* In case of a template, prefer use of typename keyword over class.
[heading Specialisations and dispatching conventions]
* Algorithms are free inline functions, taking any geometry. Parameters are often one or two geometries
* There might be an overload for a strategy. The strategy takes, a.o. care of coordinate systems
* The free `inline` function forwards to a dispatch struct, specialized for the geometry type (so for point, polygon, etc.)
* They have an `static` (`inline`) function called apply
* The dispatch struct calls, or is derived from, an struct implemented in namespace detail
* There the same: a `struct` with a `static` (`inline`) function called apply
* This way the implementation structs are building blocks, they can be reused
* In fact they are reused often by the multi-versions of the algorithms
```
namespace boost { namespace geometry
{
namespace detail { namespace foo
{
template <typename Point>
struct foo_point
{
// template parameters here
static inline int apply(Point const& p)
{
// do something here
return 1;
}
};
}} // namespace detail::foo
namespace dispatch
{
template
<
Geometry,
Tag = typename geometry::tag<Geometry>::type
>
struct foo
{
};
// Specialization for POINT
...
} // namespace dispatch
template <typename Point>
inline int foo(Point const& point)
{
return dispatch<Point>::apply(point);
}
}} // namespace boost::geometry
```
[heading Contributing code]
* Create a patch, open a ticket in the Boost Trac with your patch attached.
* Alternatively, post your patch to the Boost.Geometry mailing list.
* If you contribute a code, always try to provide a minimal test for it.
[endsect]