From 3361fc590178518661a4610e8232c8162bff9e07 Mon Sep 17 00:00:00 2001 From: Ward Fisher Date: Thu, 21 Dec 2023 09:39:44 -0700 Subject: [PATCH] Clean up doxygen warnings that were being treated as failures. --- docs/dispatch.md | 2 +- docs/filters.md | 22 ++++++++++++++++++++++ docs/internal.md | 4 ++-- docs/nczarr.md | 16 ++++++++-------- 4 files changed, 33 insertions(+), 11 deletions(-) diff --git a/docs/dispatch.md b/docs/dispatch.md index cbc6b2ae7..a3a59baab 100644 --- a/docs/dispatch.md +++ b/docs/dispatch.md @@ -520,7 +520,7 @@ Modifying the dispatch version requires two steps: The two should agree in value. -### NC_DISPATCH_VERSION Incompatibility +## NC_DISPATCH_VERSION Incompatibility When dynamically adding a dispatch table -- in nc_def_user_format (see libdispatch/dfile.c) -- diff --git a/docs/filters.md b/docs/filters.md index cf1c547fd..75aae299d 100644 --- a/docs/filters.md +++ b/docs/filters.md @@ -65,6 +65,28 @@ The concept of a variable-sized type is defined as follows: then that compound type is variable-sized. 4. All other types are fixed-size. +## A Warning on Backward Compatibility {#filters_compatibility} + +The API defined in this document should accurately reflect the +current state of filters in the netCDF-c library. Be aware that +there was a short period in which the filter code was undergoing +some revision and extension. Those extensions have largely been +reverted. Unfortunately, some users may experience some +compilation problems for previously working code because of +these reversions. In that case, please revise your code to +adhere to this document. Apologies are extended for any +inconvenience. + +A user may encounter an incompatibility if any of the following appears in user code. + +* The function *\_nc\_inq\_var\_filter* was returning the error value NC\_ENOFILTER if a variable had no associated filters. + It has been reverted to the previous case where it returns NC\_NOERR and the returned filter id was set to zero if the variable had no filters. +* The function *nc\_inq\_var\_filterids* was renamed to *nc\_inq\_var\_filter\_ids*. +* Some auxilliary functions for parsing textual filter specifications have been moved to the file *netcdf\_aux.h*. See [Appendix A](#filters_appendixa). +* All of the "filterx" functions have been removed. This is unlikely to cause problems because they had limited visibility. + +For additional information, see [Appendix B](#filters_appendixb). + ## Enabling A HDF5 Compression Filter {#filters_enable} HDF5 supports dynamic loading of compression filters using the diff --git a/docs/internal.md b/docs/internal.md index 2ddf3fb74..7d7ce2fe5 100644 --- a/docs/internal.md +++ b/docs/internal.md @@ -8,13 +8,13 @@ This document attempts to record important information about the internal architecture and operation of the netcdf-c library. It covers the following issues. -* [Including C++ Code in the netcdf-c Library](#intern_c++) +* [Including C++ Code in the netcdf-c Library](#intern_cpp) * [Managing instances of variable-length data types](#intern_vlens) * [Inferring File Types](#intern_infer) * [Adding a Standard Filter](#intern_filters) * [Test Interference](#intern_isolation) -# 1. Including C++ Code in the netcdf-c Library {#intern_c++} +# 1. Including C++ Code in the netcdf-c Library {#intern_cpp} The state of C compiler technology has reached the point where it is possible to include C++ code into the netcdf-c library diff --git a/docs/nczarr.md b/docs/nczarr.md index c4da73797..7bb35b4bd 100644 --- a/docs/nczarr.md +++ b/docs/nczarr.md @@ -449,16 +449,16 @@ Here are a couple of examples using the _ncgen_ and _ncdump_ utilities. ``` 4. Create an nczarr file using S3 as storage and keeping to the pure zarr format. ``` - ncgen -4 -lb -o "s3://s3.uswest-1.amazonaws.com/datasetbucket#mode=zarr" dataset.cdl + ncgen -4 -lb -o 's3://s3.uswest-1.amazonaws.com/datasetbucket#mode=zarr dataset.cdl ``` 5. Create an nczarr file using the s3 protocol with a specific profile ``` - ncgen -4 -lb -o "s3://datasetbucket/rootkey#mode=nczarr,awsprofile=unidata" dataset.cdl + ncgen -4 -lb -o 's3://datasetbucket/rootkey#mode=nczarr,awsprofile=unidata' dataset.cdl ``` Note that the URL is internally translated to this - ```` - https://s2.<region>.amazonaws.com/datasetbucket/rootkey#mode=nczarr,awsprofile=unidata" dataset.cdl - ```` + ``` + 'https://s2.<region>.amazonaws.com/datasetbucket/rootkey#mode=nczarr,awsprofile=unidata' dataset.cdl + ``` # References {#nczarr_bib} @@ -473,7 +473,7 @@ collections — High-performance dataset datatypes](https://docs.python.org/2/li [8] [Dynamic Filter Loading](https://support.hdfgroup.org/HDF5/doc/Advanced/DynamicallyLoadedFilters/HDF5DynamicallyLoadedFilters.pdf)
[9] [Officially Registered Custom HDF5 Filters](https://portal.hdfgroup.org/display/support/Registered+Filter+Plugins)
[10] [C-Blosc Compressor Implementation](https://github.com/Blosc/c-blosc)
-[11] [Conda-forge / packages / aws-sdk-cpp](https://anaconda.org/conda-forge/aws-sdk-cpp)
+[11] [Conda-forge packages / aws-sdk-cpp](https://anaconda.org/conda-forge/aws-sdk-cpp)
[12] [GDAL Zarr](https://gdal.org/drivers/raster/zarr.html)
# Appendix A. Building NCZarr Support {#nczarr_build} @@ -539,7 +539,7 @@ PATH="$PATH:${AWSSDKBIN}" Then the following options must be specified for cmake. ```` -DAWSSDK_ROOT_DIR=${AWSSDK_ROOT_DIR} --DAWSSDK_DIR=${AWSSDK_ROOT_DIR}/lib/cmake/AWSSDK" +-DAWSSDK_DIR=${AWSSDK_ROOT_DIR}/lib/cmake/AWSSDK ```` # Appendix B. Amazon S3 Imposed Limits {#nczarr_s3limits} @@ -578,7 +578,7 @@ can in fact be any legal JSON expression. This "convention" is currently used routinely to help support various attributes created by other packages where the attribute is a complex JSON expression. An example is the GDAL Driver -convention [12], where the value is a complex +convention [12], where the value is a complex JSON dictionary. In order for NCZarr to be as consistent as possible with Zarr Version 2,