diff --git a/ci/release/update-version.sh b/ci/release/update-version.sh index c7ea93a95..d19ccaaae 100755 --- a/ci/release/update-version.sh +++ b/ci/release/update-version.sh @@ -45,3 +45,7 @@ sed_runner 's/'"branch-.*\/RAPIDS.cmake"'/'"branch-${NEXT_SHORT_TAG}\/RAPIDS.cma for FILE in conda/environments/*.yml; do sed_runner "s/cudf=${CURRENT_SHORT_TAG}/cudf=${NEXT_SHORT_TAG}/g" ${FILE}; done + +# Doxyfile update +sed_runner "/PROJECT_NUMBER[ ]*=/ s|=.*|= ${NEXT_FULL_TAG}|g" cpp/doxygen/Doxyfile +sed_runner "/TAGFILES/ s|[0-9]\+.[0-9]\+|${NEXT_SHORT_TAG}|g" cpp/doxygen/Doxyfile diff --git a/cpp/doc/DOCUMENTATION.md b/cpp/doc/DOCUMENTATION.md deleted file mode 100644 index a767591b8..000000000 --- a/cpp/doc/DOCUMENTATION.md +++ /dev/null @@ -1,575 +0,0 @@ -# libcuspatial C++ Documentation Guide - -These guidelines apply to documenting all libcuspatial C++ source files using doxygen style -formatting although only public APIs and classes are actually -[published](https://docs.rapids.ai/api/libcuspatial/stable/index.html). - -## Copyright License - -The following is the license header comment that should appear at the beginning of every C++ -source file. - -```c++ -/* - * Copyright (c) 2022, NVIDIA CORPORATION. - * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - */ -``` - -The comment should start with `/*` and not `/**` so it is not processed by doxygen. - -Also, here are the rules for the copyright year. - -- A new file should have the year in which it was created -- A modified file should span the year it was created and the year it was modified (e.g. - `2019-2021`) - -Changing the copyright year may not be necessary if no content has changed (e.g. reformatting only). - -## Doxygen - -The [doxygen tool](http://www.doxygen.nl/manual/index.html) is used to generate HTML pages from the -C++ comments in the source code. Doxygen recognizes and parses block comments and performs -specialized output formatting when it encounters -[doxygen commands](http://www.doxygen.nl/manual/commands.html). - -There are almost 200 commands (also called tags in this document) that doxygen recognizes in comment -blocks. This document provides guidance on which commands/tags to use and how to use them in the -libcuspatial C++ source code. - -Doxygen can be customized using options in the [Doxyfile](../doxygen/Doxyfile). - -Here are some of the custom options in the Doxyfile for libcuspatial. -| Option | Setting | Description | -| ------ | ------- | ----------- | -| PROJECT_NAME | libcuspatial | Title used on the main page | -| PROJECT_NUMBER | 22.10.00 | Version number | -| EXTENSION_MAPPING | cu=C++ cuh=C++ | Process `cu` and `cuh` as C++ | -| INPUT | main_page.md ../include | Embedded markdown files and source code directories to process | -| FILE_PATTERNS | *.cpp *.hpp *.h *.c *.cu *.cuh | File extensions to process | -| EXCLUDE_PATTERNS | */detail/* */nvtx/* | Wildcard pattern to exclude paths / filenames | -| TAGFILES | rmm.tag=https://docs.rapids.ai/api/librmm/22.10 "libcudf.tag=https://docs.rapids.ai/api/libcudf/22.10" | Links to external documentation tagfiles. Versions are updated automatically at each release | -| PREDEFINED | __device__= \ __host__= | Predefined macros. Helps with CUDA declaration specifiers. | - - -## Block Comments - -Use the following style for block comments describing functions, classes and other types, groups, -and files. - -```c++ -/** - * description text and - * doxygen tags go here - */ -``` - -Doxygen comment blocks start with `/**` and end with `*/` only, and with nothing else on those -lines. Do not add dashes `-----` or extra asterisks `*****` to the first and last lines of a doxygen -block. The block must be placed immediately before the source code line to which it refers. The -block may be indented to line up vertically with the item it documents as appropriate. See the -[Example](#the-example) section below. - -Each line in the comment block between the `/**` and `*/` lines should start with a space followed -by an asterisk. Any text on these lines, including tag declarations, should start after a single -space after the asterisk. - -## Tag/Command names - -Use `@` to prefix doxygen commands (e.g. `@brief`, `@code`, etc.) - -## Markdown - -The doxygen tool supports a limited set of markdown format in the comment block including links, -tables, lists, etc. In some cases a trade-off may be required for readability in the source text -file versus the readability in the doxygen formatted web pages. For example, there are some -limitations on readability with '%' character and pipe character '|' within a markdown table. - -Avoid using direct HTML tags. Although doxygen supports markdown and markdown supports HTML tags, -the HTML support for doxygen's markdown is also limited. - -## The Example - -The following example covers most of the doxygen block comment and tag styles for documenting C++ -code in libcuspatial. - -```c++ -/** - * @file source_file.cpp - * @brief Description of source file contents - * - * Longer description of the source file contents. - */ - -/** - * @brief One sentence description of the class. - * - * @ingroup optional_predefined_group_id - * - * Longer, more detailed description of the class. - * - * @tparam T Short description of each template parameter - * @tparam U Short description of each template parameter - */ -template -class example_class { - - void get_my_int(); ///< Simple members can be documented like this - void set_my_int( int value ); ///< Try to use descriptive member names - - /** - * @brief Short, one sentence description of the member function. - * - * A more detailed description of what this function does and what - * its logic does. - * - * @code - * example_class inst; - * inst.set_my_int(5); - * int output = inst.complicated_function(1,dptr,fptr); - * @endcode - * - * @param[in] first This parameter is an input parameter to the function - * @param[in,out] second This parameter is used both as an input and output - * @param[out] third This parameter is an output of the function - * - * @return The result of the complex function - */ - T complicated_function(int first, double* second, float* third) - { - // Do not use doxygen-style block comments - // for code logic documentation. - } - - private: - int my_int; ///< An example private member variable - /// Another example of private member variable - float my_float; -}; - -/** - * @brief Short, one sentence description of this free function. - * - * @ingroup optional_predefined_group_id - * - * A detailed description must start after a blank line. - * - * @code - * template - * struct myfunctor { - * bool operator()(T input) { return input % 2 > 0; } - * }; - * free_function(myfunctor{},12); - * @endcode - * - * @throw cuspatial::logic_error if `input_argument` is negative or zero - * - * @tparam functor_type The type of the functor - * @tparam input_type The datatype of the input argument - * - * @param[in] functor The functor to be called on the input argument - * @param[in] input_argument The input argument passed into the functor - * @return The result of calling the functor on the input argument - */ -template -bool free_function(functor_type functor, input_type input_argument) -{ - CUSPATIAL_EXPECTS( input_argument > 0, "input_argument must be positive"); - return functor(input_argument); -} - -/** - * @brief Short, one sentence description. - * - * @ingroup optional_predefined_group_id - * - * Optional, longer description. - */ -enum class example_enum { - first_enum, ///< Description of the first enum - second_enum, ///< Description of the second enum - third_enum ///< Description of the third enum -}; - -/** - * @internal - * @brief The "@internal" tag can be used to indicate rendered HTML docs for a function should not - * be generated. - */ -void internal_function() -{ - ... -} -``` - -## Descriptions - -The comment description should clearly detail how the output(s) are created from any inputs. Include -any performance and any boundary considerations. Also include any limits on parameter values and if -any default values are declared. Also, try to include a short [example](#inline-examples) if -possible. - -### @brief - -The `@brief` text should be a short, one sentence description. Doxygen does not provide much space -to show this text in the output pages. Always follow the `@brief` line with a blank comment line. - -The longer description is the rest of the comment text that is not tagged with any doxygen command. - -```c++ -/** - * @brief Short description. - * - * Long description. - * -``` - -### @copydoc - -Documentation for declarations in headers should be clear and complete. -You can use the `@copydoc` tag to avoid duplicating the comment block for a function definition. - -```c++ - /** - * @copydoc complicated_function(int,double*,float*) - * - * Any extra documentation. - */ -``` - -Also, `@copydoc` is useful when documenting a `detail` function that differs only by the `stream` parameter. - -```c++ -/** - * @copydoc cudf::segmented_count_set_bits(bitmask_type const*,std::vector const&) - * - * @param[in] stream Optional CUDA stream on which to execute kernels - */ -std::vector segmented_count_set_bits(bitmask_type const* bitmask, - std::vector const& indices, - rmm::cuda_stream_view stream = cudf::default_stream_value); -``` - -Note, you must specify the whole signature of the function, including optional parameters, so that -doxygen will be able to locate it. - -### Function parameters - -The following tags should appear near the end of function comment block in the order specified here: - -| Command | Description | -| ------- | ----------- | -| [@throw](#throw) | Specify the conditions in which the function may throw an exception | -| [@tparam](#tparam) | Description for each template parameter | -| [@param](#param) | Description for each function parameter | -| [@return](#return) | Short description of object or value returned | -| [@pre](#pre) | Specify any preconditions / requirements for the function | - -#### @throw - -Add an [@throw](http://www.doxygen.nl/manual/commands.html#cmdthrow) comment line in the doxygen -block for each exception that the function may throw. You only need to include exceptions thrown by -the function itself. If the function calls another function that may throw an exception, you do not -need to document those exceptions here. - -Include the name of the exception without backtick marks so doxygen can add reference links correctly. - -```c++ - /** - * ... - * @throw cuspatial::logic_error if `input_argument` is negative or zero - */ -``` - -Using `@throws` is also acceptable but vs-code and other tools only do syntax highlighting on -`@throw`. - -#### @tparam - -Add a [@tparam](http://www.doxygen.nl/manual/commands.html#cmdtparam) comment line for each template -parameter declared by this function. The name of the parameter specified after the doxygen tag must -match exactly to the template parameter name. - -```c++ - /** - * ... - * @tparam functor_type The type of the functor - * @tparam input_type The datatype of the input argument - */ -``` - -The definition should detail the requirements of the parameter. -For example, if the template is for a functor or predicate, then describe the expected input types -and output. - -#### @param - -Add a [@param](http://www.doxygen.nl/manual/commands.html#cmdparam) comment line for each function -parameter passed to this function. The name of the parameter specified after the doxygen tag must -match the function's parameter name. Optionally, you may append `[in]`, `[out]` or `[in,out]` to the -`@param` if it is not clear from the declaration and the parameter name whether the paremeter is an -input parameter or an output parameter. This is especially helpful for the header-only API where -it may be hard to distinguish input and output iterators. - -```c++ - /** - * ... - * @param[in] first This parameter is an input parameter to the function - * @param[in,out] second This parameter is used both as an input and output - * @param[out] third This parameter is an output of the function - */ -``` - -It is also recommended to vertically align the 3 columns of text if possible to make it easier to -read in a source code editor. - -#### @return - -Add a single [@return](http://www.doxygen.nl/manual/commands.html#cmdreturn) comment line at the end -of the comment block if the function returns an object or value. Include a brief description of what -is returned. - -```c++ -/** - * ... - * - * @return A new column of type INT32 and no nulls - */ -``` - -Do not include the type of the object returned with the `@return` comment. - -#### @pre - -Add a [@pre](https://www.doxygen.nl/manual/commands.html#cmdpre) comment line for each precondition -of the function. For example, assumptions about device accessibility or range of iterators. One -common example is a precondition that input and output iterator ranges do not partially overlap. -Often these are requirements that it is impossible or expensive to enforce at run time. Violations -of preconditions often result in undefined behavior rather than exceptions. - -```c++ -/** - * ... - * - * @pre All iterators must have the same `Location` type, with the same underlying floating-point - * coordinate type (e.g. `cuspatial::vec_2d`). - */ -``` - -### Inline Examples - -It is usually helpful to include a source code example inside your comment block when documenting a -function or other declaration. Use the [@code](http://www.doxygen.nl/manual/commands.html#cmdcode) -and [@endcode](http://www.doxygen.nl/manual/commands.html#cmdendcode) pair to include inline -examples. - -Doxygen supports syntax highlighting for C++ and several other programming languages (e.g. Python, -Java). By default, the `@code` tag uses syntax highlighting based on the source code in which it is -found. - -```c++ - /** - * ... - * - * @code - * auto result = rmm::device_uvector(...); - * @endcode - */ -``` - -You can specify a different language by indicating the file extension in the tag: - -```c++ - /** - * ... - * - * @code{.py} - * import cudf - * s = cudf.Series([1,2,3]) - * @endcode - */ -``` - -If you wish to use pseudocode in your example, use the following: - -```c++ - /** - * ... - * - * Sometimes pseudo-code is clearer. - * @code{.pseudo} - * s = int column of [ 1, 2, null, 4 ] - * r = fill( s, [1, 2], 0 ) - * r is now [ 1, 0, 0, 4 ] - * @endcode - */ -``` - -When writing example snippets, using fully qualified class names allows doxygen to add reference -links to the example. - -```c++ - /** - * ... - * - * @code - * auto result1 = make_column( ); // reference link will not be created - * auto result2 = cudf::make_column( ); // reference link will be created - * @endcode - */ -``` - -Although using three backtick marks `` ``` `` for example blocks will work too, they do not stand -out as well in vs-code and other source editors. - -Do not use the `@example` tag in the comments for a declaration, or doxygen will interpret the -entire source file as example source code. The source file is then published under a separate -_Examples_ page in the output. - -### Deprecations - -Add a single [@deprecated](https://www.doxygen.nl/manual/commands.html#cmddeprecated) comment line -to comment blocks for APIs that will be removed in future releases. Mention alternative / -replacement APIs in the deprecation comment. - -```c++ -/** - * ... - * - * @deprecated This function is deprecated. Use another new function instead. - */ -``` - -## Namespaces - -Doxygen output includes a _Namespaces_ page that shows all the namespaces declared with comment -blocks in the processed files. Here is an example of a doxygen description comment for a namespace -declaration. - -```c++ -/** - * @brief cuSpatial interfaces - * - * This is the top-level namespace which contains all cuSpatial functions and types. - */ -namespace cuspatial { -``` - -A description comment should be included only once for each unique namespace declaration. Otherwise, -if more than one description is found, doxygen aggregates the descriptions in an arbitrary order in -the output pages. - -If you introduce a new namespace, provide a description block for only one declaration and not for -every occurrence. - -## Groups/Modules - -Grouping declarations into modules helps users to find APIs in the doxygen pages. Generally, common -functions are already grouped logically into header files but doxygen does not automatically group -them this way in its output. - -The doxygen output includes a _Modules_ page that organizes items into groups specified using the -[Grouping doxygen commands](http://www.doxygen.nl/manual/grouping.html). These commands can group -common functions across header files, source files, and even namespaces. Groups can also be nested -by defining new groups within existing groups. - -For libcuspatial, all the group hierarchy is defined in the -[doxygen_groups.h](../include/doxygen_groups.h) header file. The `doxygen_groups.h` file does not -need to be included in any other source file, because the definitions in this file are used only by -the doxygen tool to generate groups in the _Modules_ page. Modify this file only to add or update -groups. The existing groups have been carefully structured and named, so new groups should be added -thoughtfully. - -When creating a new API, specify its group using the -[@ingroup](http://www.doxygen.nl/manual/commands.html#cmdingroup) tag and the group reference id -from the [doxygen_groups.h](../include/doxygen_groups.h) file. - -```c++ -namespace cuspatial { - -/** - * @brief ... - * - * @ingroup distance - * - * @tparam... - * @param ... - * @return ... - */ -template -OutputIt pairwise_point_distance(Cart2dItA points1_first, ...); - -} // namespace cuspatial -``` - -You can also use the `@addtogroup` with a `@{ ... @}` pair to automatically include doxygen comment -blocks as part of a group. - -```c++ -namespace cuspatial { -/** - * @addtogroup coordinate_transform - * @{ - */ - -/** - * @brief ... - * - * @param ... - * @return ... - */ -template -OutputIt pairwise_point_distance(Cart2dItA points1_first, ...); - -/** @} */ -} // namespace cuspatial -``` - -This just saves adding `@ingroup` to individual doxygen comment blocks within a file. Make sure a -blank line is included after the `@addtogroup` command block so doxygen knows it does not apply to -whatever follows in the source code. Note that doxygen will not assign groups to items if the -`@addtogroup` with `@{ ... @}` pair includes a namespace declaration. So include the `@addtogroup` -and `@{ ... @}` between the namespace declaration braces as shown in the example above. - -Summary of groups tags -| Tag/Command | Where to use | -| ----------- | ------------ | -| `@defgroup` | For use only in [doxygen_groups.h](../include/doxygen_groups.h) and should include the group's title. | -| `@ingroup` | Use inside individual doxygen block comments for declaration statements in a header file. | -| `@addtogroup` | Use instead of `@ingroup` for multiple declarations in the same file within a namespace declaration. Do not specify a group title. | -| `@{ ... @}` | Use only with `@addtogroup`. | - -## Build Doxygen Output - -We recommend installing Doxygen using conda (`conda install doxygen`) or a Linux package manager -(`sudo apt install doxygen`). Alternatively you can -[build and install doxygen from source](http://www.doxygen.nl/manual/install.html). - -To build the libcuspatial HTML documentation simply run the `doxygen` command from the `cpp/doxygen` -directory containing the `Doxyfile`. The libcudf documentation can also be built using -`cmake --build . --target docs_cudf` from the cmake build directory (e.g. `cpp/build/release`). - -Doxygen reads and processes all appropriate source files under the `cpp/include/` directory. The -output is generated in the `cpp/doxygen/html/` directory. You can load the local `index.html` file -generated there into any web browser to view the result. - -To view docs built on a remote server, you can run a simple HTTP server using Python: -`cd html && python -m http.server`. Then open `http://:8000` in your local web browser, -inserting the IP address of the machine on which you ran the HTTP server. - -The doxygen output is intended for building documentation only for the public APIs and classes. For -example, the output should not include documentation for `detail` or `/src` files, and these -directories are excluded in the `Doxyfile` configuration. When published by the RAPIDS build/CI -system, the doxygen output appears on the -[RAPIDS web site](https://docs.rapids.ai/api/libcuspatial/stable/index.html). diff --git a/cpp/doxygen/Doxyfile b/cpp/doxygen/Doxyfile index c21d67546..1ac30f507 100644 --- a/cpp/doxygen/Doxyfile +++ b/cpp/doxygen/Doxyfile @@ -38,7 +38,7 @@ PROJECT_NAME = "libcuspatial" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 22.06.00 +PROJECT_NUMBER = 22.10.00 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a @@ -726,7 +726,7 @@ FILE_VERSION_FILTER = # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE # tag is left empty. -LAYOUT_FILE = +LAYOUT_FILE = DoxygenLayout.xml # The CITE_BIB_FILES tag can be used to specify one or more bib files containing # the reference definitions. This must be a list of .bib files. The .bib @@ -815,6 +815,11 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = main_page.md \ + developer_guide/BENCHMARKING.md \ + developer_guide/DOCUMENTATION.md \ + developer_guide/DEVELOPER_GUIDE.md \ + developer_guide/TESTING.md \ + developer_guide/REFACTORING_GUIDE.md \ ../include # This tag can be used to specify the character encoding of the source files @@ -950,7 +955,7 @@ INPUT_FILTER = # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. -FILTER_PATTERNS = +FILTER_PATTERNS = *.md=./modify_fences.sh # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will also be used to filter the input files that are used for @@ -2166,7 +2171,7 @@ SKIP_FUNCTION_MACROS = YES # the path). If a tag file is not located in the directory in which doxygen is # run, you must also specify the path to the tagfile here. -TAGFILES = rmm.tag=https://docs.rapids.ai/api/librmm/22.06 "libcudf.tag=https://docs.rapids.ai/api/libcudf/22.06" +TAGFILES = rmm.tag=https://docs.rapids.ai/api/librmm/22.10 "libcudf.tag=https://docs.rapids.ai/api/libcudf/22.10" # When a file name is specified after GENERATE_TAGFILE, doxygen will create a # tag file that is based on the input files it reads. See section "Linking to diff --git a/cpp/doxygen/DoxygenLayout.xml b/cpp/doxygen/DoxygenLayout.xml new file mode 100644 index 000000000..790be3755 --- /dev/null +++ b/cpp/doxygen/DoxygenLayout.xml @@ -0,0 +1,195 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/cpp/doc/BENCHMARKING.md b/cpp/doxygen/developer_guide/BENCHMARKING.md similarity index 92% rename from cpp/doc/BENCHMARKING.md rename to cpp/doxygen/developer_guide/BENCHMARKING.md index fdae9e98a..7df628973 100644 --- a/cpp/doc/BENCHMARKING.md +++ b/cpp/doxygen/developer_guide/BENCHMARKING.md @@ -25,8 +25,8 @@ CUDA computations and operations like copies are typically asynchronous with res so it is important to carefully synchronize in order to ensure the benchmark timing is not stopped before the feature you are benchmarking has completed. An RAII helper class `cuda_event_timer` is provided in `cpp/benchmarks/synchronization/synchronization.hpp` to help with this. This class -can also optionally clear the GPU L2 cache in order to ensure cache hits do not artificially inflate -performance in repeated iterations. +can also optionally clear the GPU L2 cache in order to ensure cache hits do not artificially +inflate performance in repeated iterations. ## Data generation @@ -46,6 +46,7 @@ sets larger than this point is generally not helpful, except in specific cases w exercises different code and can therefore uncover regressions that smaller benchmarks will not (this should be rare). -Generally we should benchmark public APIs. Benchmarking detail functions and/or internal utilities should -only be done if detecting regressions in them would be sufficiently difficult to do from public API -benchmarks. + +Generally we should benchmark public APIs. Benchmarking detail functions and/or internal utilities +should only be done if detecting regressions in them would be sufficiently difficult to do from +public API benchmarks. diff --git a/cpp/doc/DEVELOPER_GUIDE.md b/cpp/doxygen/developer_guide/DEVELOPER_GUIDE.md similarity index 98% rename from cpp/doc/DEVELOPER_GUIDE.md rename to cpp/doxygen/developer_guide/DEVELOPER_GUIDE.md index f448446a1..8986a5908 100644 --- a/cpp/doc/DEVELOPER_GUIDE.md +++ b/cpp/doxygen/developer_guide/DEVELOPER_GUIDE.md @@ -1,4 +1,4 @@ -# libcuspatial C++ Developer Guide +# libcuspatial C++ Developer Guide {#DEVELOPER_GUIDE} This document serves as a guide for contributors to libcuspatial C++ code. Developers should also refer to these additional files for further documentation of libcuspatial best practices. @@ -6,6 +6,8 @@ refer to these additional files for further documentation of libcuspatial best p * [Documentation Guide](DOCUMENTATION.md) for guidelines on documenting libcuspatial code. * [Testing Guide](TESTING.md) for guidelines on writing unit tests. * [Benchmarking Guide](BENCHMARKING.md) for guidelines on writing unit benchmarks. +* [Refactoring Guide](REFACTORING_GUIDE.md) for guidelines on refactoring legacy column-based APIs into + header-only APIs. # Overview @@ -200,7 +202,7 @@ respectively. All memory resource parameters should be defaulted to use the retu This section provides specifics about the structure and implementation of cuSpatial API functions. -## Column-based cuSpatial API +## Column-based cuSpatial API libcuspatial's column-based API is designed to integrate seamlessly with other RAPIDS libraries, notably cuDF. To that end, this API uses `cudf::column` and `cudf::table` data structures as input @@ -321,7 +323,7 @@ auto foo = [&out0 = out0] { }; ``` -## Header-only cuSpatial API +## Header-only cuSpatial API For C++ users and developers who do not also use libcudf or other RAPIDS APIS, depending on libcudf could be a barrier to adoption of libcuspatial. libcudf is a very large library and building it @@ -532,7 +534,7 @@ libcuspatial code eschews raw pointers and direct memory allocation. Use RMM cla use [`device_memory_resource`](https://github.com/rapidsai/rmm/#device_memory_resource) for device memory allocation with automated lifetime management. -#### `rmm::device_buffer` +#### rmm::device_buffer Allocates a specified number of bytes of untyped, uninitialized device memory using a `device_memory_resource`. If no resource is explicitly provided, uses `rmm::mr::get_current_device_resource()`. @@ -558,7 +560,7 @@ custom_memory_resource *mr...; rmm::device_buffer custom_buff(100, mr, stream); ``` -#### `rmm::device_scalar` +#### rmm::device_scalar Allocates a single element of the specified type initialized to the specified value. Use this for scalar input/outputs into device kernels, e.g., reduction results, null count, etc. This is effectively a convenience wrapper around a `rmm::device_vector` of length 1. @@ -576,7 +578,7 @@ kernel<<<...>>>(int_scalar.data(),...); int host_value = int_scalar.value(); ``` -#### `rmm::device_vector` +#### rmm::device_vector Allocates a specified number of elements of the specified type. If no initialization value is provided, all elements are default initialized (this incurs a kernel launch). @@ -590,7 +592,7 @@ utilities enable creation of `uvector`s from host-side vectors, or creating zero `uvector`s, so that they are as convenient to use as `device_vector`. Avoiding `device_vector` has a number of benefits, as described in the following section on `rmm::device_uvector`. -#### `rmm::device_uvector` +#### rmm::device_uvector Similar to a `device_vector`, allocates a contiguous set of elements in device memory but with key differences: @@ -632,7 +634,7 @@ group a broad set of functions, further namespaces may be used. Many functions are not meant for public use, so place them in either the `detail` or an *anonymous* namespace, depending on the situation. -#### `detail` namespace +#### detail namespace Functions or objects that will be used across *multiple* translation units (i.e., source files), should be exposed in an internal header file and placed in the `detail` namespace. Example: diff --git a/cpp/doxygen/developer_guide/DOCUMENTATION.md b/cpp/doxygen/developer_guide/DOCUMENTATION.md new file mode 100644 index 000000000..9271634d4 --- /dev/null +++ b/cpp/doxygen/developer_guide/DOCUMENTATION.md @@ -0,0 +1,537 @@ +# libcuspatial C++ Documentation Guide + +These guidelines apply to documenting all libcuspatial C++ source files using doxygen style +formatting although only public APIs and classes are actually +[published](https://docs.rapids.ai/api/libcuspatial/stable/index.html). + +## Copyright License + +The following is the license header comment that should appear at the beginning of every C++ +source file. + + /* + * Copyright (c) 2022, NVIDIA CORPORATION. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + + +The comment should start with `/*` and not `/**` so it is not processed by doxygen. + +Also, here are the rules for the copyright year. + +- A new file should have the year in which it was created +- A modified file should span the year it was created and the year it was modified (e.g. + `2019-2021`) + +Changing the copyright year may not be necessary if no content has changed (e.g. reformatting only). + +## Doxygen + +The [doxygen tool](https://www.doxygen.nl/manual/index.html) is used to generate HTML pages from the +C++ comments in the source code. Doxygen recognizes and parses block comments and performs +specialized output formatting when it encounters +[doxygen commands](https://www.doxygen.nl/manual/commands.html). + +There are almost 200 commands (also called tags in this document) that doxygen recognizes in comment +blocks. This document provides guidance on which commands/tags to use and how to use them in the +libcuspatial C++ source code. + +The doxygen process can be customized using options in the [Doxyfile](../doxygen/Doxyfile). + +Here are some of the custom options in the Doxyfile for libcuspatial. +| Option | Setting | Description | +| ------ | ------- | ----------- | +| PROJECT_NAME | libcuspatial | Title used on the main page | +| PROJECT_NUMBER | 22.10.00 | Version number | +| EXTENSION_MAPPING | cu=C++ cuh=C++ | Process `cu` and `cuh` as C++ | +| INPUT | main_page.md ../include | Embedded markdown files and source code directories to process | +| FILE_PATTERNS | *.cpp *.hpp *.h *.c *.cu *.cuh | File extensions to process | +| EXCLUDE_PATTERNS | */detail/* */nvtx/* | Wildcard pattern to exclude paths / filenames | +| TAGFILES | rmm.tag=https://docs.rapids.ai/api/librmm/22.10 "libcudf.tag=https://docs.rapids.ai/api/libcudf/22.10" | Links to external documentation tagfiles. Versions are updated automatically at each release | +| PREDEFINED | __device__= \ __host__= | Predefined macros. Helps with CUDA declaration specifiers. | + + +## Block Comments + +Use the following style for block comments describing functions, classes and other types, groups, +and files. + + /** + * description text and + * doxygen tags go here + */ + +Doxygen comment blocks start with `/**` and end with `*/` only, and with nothing else on those +lines. Do not add dashes `-----` or extra asterisks `*****` to the first and last lines of a doxygen +block. The block must be placed immediately before the source code line to which it refers. The +block may be indented to line up vertically with the item it documents as appropriate. See the +[Example](#the-example) section below. + +Each line in the comment block between the `/**` and `*/` lines should start with a space followed +by an asterisk. Any text on these lines, including tag declarations, should start after a single +space after the asterisk. + +## Tag/Command names + +Use @ to prefix doxygen commands (e.g. \@brief, \@code, etc.) + +## Markdown + +The doxygen tool supports a limited set of markdown format in the comment block including links, +tables, lists, etc. In some cases a trade-off may be required for readability in the source text +file versus the readability in the doxygen formatted web pages. For example, there are some +limitations on readability with '%' character and pipe character '|' within a markdown table. + +Avoid using direct HTML tags. Although doxygen supports markdown and markdown supports HTML tags, +the HTML support for doxygen's markdown is also limited. + +## The Example + +The following example covers most of the doxygen block comment and tag styles for documenting C++ +code in libcuspatial. + + /** + * @file source_file.cpp + * @brief Description of source file contents + * + * Longer description of the source file contents. + */ + + /** + * @brief One sentence description of the class. + * + * @ingroup optional_predefined_group_id + * + * Longer, more detailed description of the class. + * + * @tparam T Short description of each template parameter + * @tparam U Short description of each template parameter + */ + template + class example_class { + + void get_my_int(); ///< Simple members can be documented like this + void set_my_int( int value ); ///< Try to use descriptive member names + + /** + * @brief Short, one sentence description of the member function. + * + * A more detailed description of what this function does and what + * its logic does. + * + * @code + * example_class inst; + * inst.set_my_int(5); + * int output = inst.complicated_function(1,dptr,fptr); + * @endcode + * + * @param[in] first This parameter is an input parameter to the function + * @param[in,out] second This parameter is used both as an input and output + * @param[out] third This parameter is an output of the function + * + * @return The result of the complex function + */ + T complicated_function(int first, double* second, float* third) + { + // Do not use doxygen-style block comments + // for code logic documentation. + } + + private: + int my_int; ///< An example private member variable + }; + + /** + * @brief Short, one sentence description of this free function. + * + * @ingroup optional_predefined_group_id + * + * A detailed description must start after a blank line. + * + * @code + * template + * struct myfunctor { + * bool operator()(T input) { return input % 2 > 0; } + * }; + * free_function(myfunctor{},12); + * @endcode + * + * @throw cuspatial::logic_error if `input_argument` is negative or zero + * + * @tparam functor_type The type of the functor + * @tparam input_type The datatype of the input argument + * + * @param[in] functor The functor to be called on the input argument + * @param[in] input_argument The input argument passed into the functor + * @return The result of calling the functor on the input argument + */ + template + bool free_function(functor_type functor, input_type input_argument) + { + CUSPATIAL_EXPECTS( input_argument > 0, "input_argument must be positive"); + return functor(input_argument); + } + + /** + * @brief Short, one sentence description. + * + * @ingroup optional_predefined_group_id + * + * Optional, longer description. + */ + enum class example_enum { + first_enum, ///< Description of the first enum + second_enum, ///< Description of the second enum + third_enum ///< Description of the third enum + }; + + /** + * @internal + * @brief The "@internal" tag can be used to indicate rendered HTML docs for a function should not + * be generated. + */ + void internal_function() + { + ... + } + +## Descriptions + +The comment description should clearly detail how the output(s) are created from any inputs. Include +any performance and any boundary considerations. Also include any limits on parameter values and if +any default values are declared. Also, try to include a short [example](#inline-examples) if +possible. + +### \@brief + +The [\@brief](https://www.doxygen.nl/manual/commands.html#cmdbrief) text should be a short, one +sentence description. Doxygen does not provide much space to show this text in the output pages. +Always follow the \@brief line with a blank comment line. + +The longer description is the rest of the comment text that is not tagged with any doxygen command. + + /** + * @brief Short description. + * + * Long description. + */ + + +### \@copydoc + +Documentation for declarations in headers should be clear and complete. +You can use the [\@copydoc](https://www.doxygen.nl/manual/commands.html#cmdcopydoc) tag to avoid +duplicating the comment block for a function definition. + + /** + * @copydoc complicated_function(int,double*,float*) + * + * Any extra documentation. + */ + + +Also, \@copydoc is useful when documenting a `detail` function that differs only by the `stream` parameter. + + /** + * @copydoc cudf::segmented_count_set_bits(bitmask_type const*,std::vector const&) + * + * @param[in] stream Optional CUDA stream on which to execute kernels + */ + std::vector segmented_count_set_bits(bitmask_type const* bitmask, + std::vector const& indices, + rmm::cuda_stream_view stream = cudf::default_stream_value); + +Note, you must specify the whole signature of the function, including optional parameters, so that +doxygen will be able to locate it. + +### Function parameters + +The following tags should appear near the end of function comment block in the order specified here: + +| Command | Description | +| ------- | ----------- | +| [\@throw](#throw) | Specify the conditions in which the function may throw an exception | +| [\@tparam](#tparam) | Description for each template parameter | +| [\@param](#param) | Description for each function parameter | +| [\@return](#return) | Short description of object or value returned | +| [\@pre](#pre) | Specify any preconditions / requirements for the function | + +#### \@throw + +Add an [\@throw](https://www.doxygen.nl/manual/commands.html#cmdthrow) comment line in the doxygen +block for each exception that the function may throw. You only need to include exceptions thrown by +the function itself. If the function calls another function that may throw an exception, you do not +need to document those exceptions here. + +Include the name of the exception without backtick marks so doxygen can add reference links correctly. + + /** + * ... + * @throw cuspatial::logic_error if `input_argument` is negative or zero + */ + +Using \@throws is also acceptable but VS code and other tools only do syntax highlighting on +\@throw. + +#### \@tparam + +Add a [\@tparam](https://www.doxygen.nl/manual/commands.html#cmdtparam) comment line for each +template parameter declared by this function. The name of the parameter specified after the doxygen +tag must match exactly to the template parameter name. + + /** + * ... + * @tparam functor_type The type of the functor + * @tparam input_type The datatype of the input argument + */ + +The definition should detail the requirements of the parameter. +For example, if the template is for a functor or predicate, then describe the expected input types +and output. + +#### \@param + +Add a [\@param](https://www.doxygen.nl/manual/commands.html#cmdparam) comment line for each function +parameter passed to this function. The name of the parameter specified after the doxygen tag must +match the function's parameter name. Also include append `[in]`, `[out]` or `[in,out]` to the +\@param if it is not clear from the declaration and the parameter name itself. + + /** + * ... + * @param[in] first This parameter is an input parameter to the function + * @param[in,out] second This parameter is used both as an input and output + * @param[out] third This parameter is an output of the function + */ + +It is also recommended to vertically align the 3 columns of text if possible to make it easier to +read in a source code editor. + +#### \@return + +Add a single [\@return](https://www.doxygen.nl/manual/commands.html#cmdreturn) comment line at the end +of the comment block if the function returns an object or value. Include a brief description of what +is returned. + + /** + * ... + * + * @return A new column of type INT32 and no nulls + */ + +Do not include the type of the object returned with the `@return` comment. + +#### \@pre + +Add a [\@pre](https://www.doxygen.nl/manual/commands.html#cmdpre) comment line for each precondition +of the function. For example, assumptions about accessibility or range of iterators. + + /** + * ... + * + * @pre All iterators must have the same `Location` type, with the same underlying floating-point + * coordinate type (e.g. `cuspatial::vec_2d`). + */ + +### Inline Examples + +It is usually helpful to include a source code example inside your comment block when documenting a +function or other declaration. Use the [\@code](https://www.doxygen.nl/manual/commands.html#cmdcode) +and [\@endcode](https://www.doxygen.nl/manual/commands.html#cmdendcode) pair to include inline +examples. + +Doxygen supports syntax highlighting for C++ and several other programming languages (e.g. Python, +Java). By default, the \@code tag uses syntax highlighting based on the source code in which it is +found. + + /** + * ... + * + * @code + * auto result = rmm::device_uvector(...); + * @endcode + */ + +You can specify a different language by indicating the file extension in the tag: + + /** + * ... + * + * @code{.py} + * import cudf + * s = cudf.Series([1,2,3]) + * @endcode + */ + +If you wish to use pseudocode in your example, use the following: + + /** + * ... + * + * Sometimes pseudo-code is clearer. + * @code{.pseudo} + * s = int column of [ 1, 2, null, 4 ] + * r = fill( s, [1, 2], 0 ) + * r is now [ 1, 0, 0, 4 ] + * @endcode + */ + +When writing example snippets, using fully qualified class names allows doxygen to add reference +links to the example. + + /** + * ... + * + * @code + * auto result1 = make_column( ); // reference link will not be created + * auto result2 = cudf::make_column( ); // reference link will be created + * @endcode + */ + +Although using three backtick marks \`\`\` for example blocks will work too, they do not stand +out as well in VS code and other source editors. + +Do not use the \@example tag in the comments for a declaration, or doxygen will interpret the +entire source file as example source code. The source file is then published under a separate +_Examples_ page in the output. + +### Deprecations + +Add a single [\@deprecated](https://www.doxygen.nl/manual/commands.html#cmddeprecated) comment line +to comment blocks for APIs that will be removed in future releases. Mention alternative / +replacement APIs in the deprecation comment. + + /** + * ... + * + * @deprecated This function is deprecated. Use another new function instead. + */ + +## Namespaces + +Doxygen output includes a _Namespaces_ page that shows all the namespaces declared with comment +blocks in the processed files. Here is an example of a doxygen description comment for a namespace +declaration. + + /** + * @brief cuSpatial interfaces + * + * This is the top-level namespace which contains all cuSpatial functions and types. + */ + namespace cuspatial { + +A description comment should be included only once for each unique namespace declaration. Otherwise, +if more than one description is found, doxygen aggregates the descriptions in an arbitrary order in +the output pages. + +If you introduce a new namespace, provide a description block for only one declaration and not for +every occurrence. + +## Groups/Modules + +Grouping declarations into modules helps users to find APIs in the doxygen pages. Generally, common +functions are already grouped logically into header files but doxygen does not automatically group +them this way in its output. + +The doxygen output includes a _Modules_ page that organizes items into groups specified using the +[Grouping doxygen commands](https://www.doxygen.nl/manual/grouping.html). These commands can group +common functions across header files, source files, and even namespaces. Groups can also be nested +by defining new groups within existing groups. + +For libcuspatial, all the group hierarchy is defined in the +[doxygen_groups.h](../include/doxygen_groups.h) header file. The `doxygen_groups.h` file does not +need to be included in any other source file, because the definitions in this file are used only by +the doxygen tool to generate groups in the _Modules_ page. Modify this file only to add or update +groups. The existing groups have been carefully structured and named, so new groups should be added +thoughtfully. + +When creating a new API, specify its group using the +[\@ingroup](https://www.doxygen.nl/manual/commands.html#cmdingroup) tag and the group reference id +from the [doxygen_groups.h](../include/doxygen_groups.h) file. + + namespace cuspatial { + + /** + * @brief ... + * + * @ingroup distance + * + * @tparam... + * @param ... + * @return ... + */ + template + OutputIt pairwise_point_distance(Cart2dItA points1_first, ...); + + } // namespace cuspatial + +You can also use the \@addtogroup with a `@{ ... @}` pair to automatically include doxygen comment +blocks as part of a group. + + namespace cuspatial { + /** + * @addtogroup coordinate_transform + * @{ + */ + + /** + * @brief ... + * + * @param ... + * @return ... + */ + template + OutputIt pairwise_point_distance(Cart2dItA points1_first, ...); + + /** @} */ + } // namespace cuspatial + +This just saves adding \@ingroup to individual doxygen comment blocks within a file. Make sure a +blank line is included after the \@addtogroup command block so doxygen knows it does not apply to +whatever follows in the source code. Note that doxygen will not assign groups to items if the +\@addtogroup with `@{ ... @}` pair includes a namespace declaration. So include the \@addtogroup +and `@{ ... @}` between the namespace declaration braces as shown in the example above. + +Summary of groups tags +| Tag/Command | Where to use | +| ----------- | ------------ | +| \@defgroup | For use only in [doxygen_groups.h](../include/doxygen_groups.h) and should include the group's title. | +| \@ingroup | Use inside individual doxygen block comments for declaration statements in a header file. | +| \@addtogroup | Use instead of \@ingroup for multiple declarations in the same file within a namespace declaration. Do not specify a group title. | +| `@{ ... @}` | Use only with \@addtogroup. | + +See [doxygen_groups.h](../include/doxygen_groups.h) for a list of existing groups. + +## Build Doxygen Output + +We recommend installing Doxygen using conda (`conda install doxygen`) or a Linux package manager +(`sudo apt install doxygen`). Alternatively you can +[build and install doxygen from source](https://www.doxygen.nl/manual/install.html). + +To build the libcuspatial HTML documentation simply run the `doxygen` command from the `cpp/doxygen` +directory containing the `Doxyfile`. The libcuspatial documentation can also be built using +`cmake --build . --target docs_cuspatial` from the cmake build directory (e.g. +`cpp/build/release`). + +Doxygen reads and processes all appropriate source files under the `cpp/include/` directory. The output is generated in the `cpp/doxygen/html/` directory. You can load the local +`index.html` file generated there into any web browser to view the result. + +To view docs built on a remote server, you can run a simple HTTP server using Python: +`cd html && python -m http.server`. Then open `http://:8000` in your local web browser, +inserting the IP address of the machine on which you ran the HTTP server. + +The doxygen output is intended for building documentation only for the public APIs and classes. For +example, the output should not include documentation for `detail` or `/src` files, and these +directories are excluded in the `Doxyfile` configuration. When published by the RAPIDS build/CI +system, the doxygen output appears on the +[RAPIDS web site](https://docs.rapids.ai/api/libcuspatial/stable/index.html). diff --git a/cpp/doc/libcuspatial_refactoring_guide.md b/cpp/doxygen/developer_guide/REFACTORING_GUIDE.md similarity index 80% rename from cpp/doc/libcuspatial_refactoring_guide.md rename to cpp/doxygen/developer_guide/REFACTORING_GUIDE.md index e73573da5..3a7e92b4d 100644 --- a/cpp/doc/libcuspatial_refactoring_guide.md +++ b/cpp/doxygen/developer_guide/REFACTORING_GUIDE.md @@ -30,7 +30,7 @@ only libcuspatial API, we can avoid problem 1 and problem 2 for users of the leg Following is an example iterator-based API for `cuspatial::haversine_distance`. (See below for discussion of API documentation.) -```C++ +```c++ template `. - * @tparam T The underlying coordinate type. Must be a floating-point type. - * - * @pre `a_lonlat_first` may equal `distance_first`, but the range `[a_lonlat_first, a_lonlat_last)` - * shall not overlap the range `[distance_first, distance_first + (a_lonlat_last - a_lonlat_last)) - * otherwise. - * @pre `b_lonlat_first` may equal `distance_first`, but the range `[b_lonlat_first, b_lonlat_last)` - * shall not overlap the range `[distance_first, distance_first + (b_lonlat_last - b_lonlat_last)) - * otherwise. - * @pre All iterators must have the same `Location` type, with the same underlying floating-point - * coordinate type (e.g. `cuspatial::vec_2d`). - * - * @return Output iterator to the element past the last distance computed. - * - * [LinkLRAI]: https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator - * "LegacyRandomAccessIterator" - */ -``` + /** + * @brief Compute haversine distances between points in set A to the corresponding points in set B. + * + * Computes N haversine distances, where N is `std::distance(a_lonlat_first, a_lonlat_last)`. + * The distance for each `a_lonlat[i]` and `b_lonlat[i]` point pair is assigned to + * `distance_first[i]`. `distance_first` must be an iterator to output storage allocated for N + * distances. + * + * Computed distances will have the same units as `radius`. + * + * https://en.wikipedia.org/wiki/Haversine_formula + * + * @param[in] a_lonlat_first: beginning of range of (longitude, latitude) locations in set A + * @param[in] a_lonlat_last: end of range of (longitude, latitude) locations in set A + * @param[in] b_lonlat_first: beginning of range of (longitude, latitude) locations in set B + * @param[out] distance_first: beginning of output range of haversine distances + * @param[in] radius: radius of the sphere on which the points reside. default: 6371.0 + * (approximate radius of Earth in km) + * @param[in] stream: The CUDA stream on which to perform computations and allocate memory. + * + * @tparam LonLatItA Iterator to input location set A. Must meet the requirements of + * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible. + * @tparam LonLatItB Iterator to input location set B. Must meet the requirements of + * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible. + * @tparam OutputIt Output iterator. Must meet the requirements of + * [LegacyRandomAccessIterator][LinkLRAI] and be device-accessible. + * @tparam Location The `value_type` of `LonLatItA` and `LonLatItB`. Must be `cuspatial::vec_2d`. + * @tparam T The underlying coordinate type. Must be a floating-point type. + * + * @pre `a_lonlat_first` may equal `distance_first`, but the range `[a_lonlat_first, a_lonlat_last)` + * shall not overlap the range `[distance_first, distance_first + (a_lonlat_last - a_lonlat_last)) + * otherwise. + * @pre `b_lonlat_first` may equal `distance_first`, but the range `[b_lonlat_first, b_lonlat_last)` + * shall not overlap the range `[distance_first, distance_first + (b_lonlat_last - b_lonlat_last)) + * otherwise. + * @pre All iterators must have the same `Location` type, with the same underlying floating-point + * coordinate type (e.g. `cuspatial::vec_2d`). + * + * @return Output iterator to the element past the last distance computed. + * + * [LinkLRAI]: https://en.cppreference.com/w/cpp/named_req/RandomAccessIterator + * "LegacyRandomAccessIterator" + */ Key points: @@ -130,7 +128,7 @@ Key points: This is the existing API, unchanged by refactoring. Here is the existing `cuspatial::haversine_distance`: -```C++ +```c++ template ``` @@ -187,7 +185,7 @@ libcudf-based API, which requires run-time type dispatching. In the case of `hav a simple matter of a few static asserts and dynamic expectation checks, followed by a call to `thrust::transform` with a custom transform functor. -```C++ +```c++ template OutputIt haversine_distance(LonLatItA a_lonlat_first, LonLatItA a_lonlat_last, @@ -232,7 +230,7 @@ provided in `type_utils.hpp`. So, to refactor the libcudf-based API, we remove the following code. -```C++ +```c++ auto input_tuple = thrust::make_tuple(thrust::make_constant_iterator(static_cast(radius)), a_lon.begin(), a_lat.begin(), @@ -256,7 +254,7 @@ thrust::transform(rmm::exec_policy(stream), And replace it with the following code. -```C++ +```c++ auto lonlat_a = cuspatial::make_vec_2d_iterator(a_lon.begin(), a_lat.begin()); auto lonlat_b = cuspatial::make_vec_2d_iterator(b_lon.begin(), b_lat.begin()); diff --git a/cpp/doc/TESTING.md b/cpp/doxygen/developer_guide/TESTING.md similarity index 95% rename from cpp/doc/TESTING.md rename to cpp/doxygen/developer_guide/TESTING.md index 2cb7f7839..0e75e9d83 100644 --- a/cpp/doc/TESTING.md +++ b/cpp/doxygen/developer_guide/TESTING.md @@ -31,9 +31,9 @@ input and output. These tests live in `cpp/tests/` and can use libcudf features columns and tables. The header-only API does not depend on libcudf at all and so tests of these APIs should not include any libcudf headers. These tests currently live in `cpp/tests/experimental`. -Generally we test algorithms and business logic in the header-only API's unit tests. Column-based -API tests should only cover specifics of the column-based API, such as type handling, -input validation, and exceptions that are only thrown by that API. +Generally, we test algorithms and business logic in the header-only API's unit tests. +Column-based API tests should only cover specifics of the column-based API, such as type +handling, input validation, and exceptions that are only thrown by that API. ## Directory and File Naming diff --git a/cpp/doxygen/main_page.md b/cpp/doxygen/main_page.md index ea2a448e3..605585668 100644 --- a/cpp/doxygen/main_page.md +++ b/cpp/doxygen/main_page.md @@ -1,3 +1,21 @@ -# libcuspatial +libcuspatial is a GPU-accelerated C++ library for spatial data analysis including distance and +trajectory computations, spatial data indexing and spatial join operations. libcuspatial is +the high-performance backend for the cuSpatial Python library. -libcuspatial is a GPU-accelerated C++ library for spatial data analysis including distance and trajectory computations, spatial data indexing and spatial join operations. +libcuspatial has two interfaces. The generic header-only C++ API represents data as arrays +of structures (e.g. 2D points). The header-only API uses iterators for input and output, and is +similar in style to the C++ Standard Template Library (STL) and Thrust. All cuSpatial algorithms +are implemented in this API. + +The libcuspatial "column-based API" is a C++ API based on data types from libcudf, +[the CUDA Dataframe library C++ API](https://docs.rapids.ai/api/libcudf/nightly/index.html). The +column-based API represents spatial data as cuDF tables of type-erased columns, and layers on top +of the header-only API. + +## Useful Links + + - [cuSpatial Github Repository](https://github.com/rapidsai/cuspatial) + - [cuSpatial C++ Developer Guide](DEVELOPER_GUIDE.html) + - [cuSpatial Python API Documentation](https://docs.rapids.ai/api/cuspatial/stable/) + - [cuSpatial Python Developer Guide](https://docs.rapids.ai/api/cuspatial/stable/developer_guide/index.html)] + - [RAPIDS Home Page](https://rapids.ai) diff --git a/cpp/doxygen/modify_fences.sh b/cpp/doxygen/modify_fences.sh new file mode 100755 index 000000000..195f60d8a --- /dev/null +++ b/cpp/doxygen/modify_fences.sh @@ -0,0 +1,9 @@ +#!/bin/bash + +# Copyright (c) 2022, NVIDIA CORPORATION. + +# This script modifies the GitHub Markdown style code fences in our MD files +# into the PHP style that Doxygen supports, allowing us to display code +# properly both on the GitHub GUI and in published Doxygen documentation. + +sed 's/```c++/```{.cpp}/g' "$@"