fix: generate public API docs correctly

Makefile

@@ -33,6 +33,7 @@ install-deps:
 
 build-api-docs:
 	cd mkdocs && \
+	rm -rf docs/api && \
 	mkdir -p docs/api && \
 	doxygen Doxyfile && \
 	echo "Doxygen output created in docs/api/"

mkdocs/Doxyfile

@@ -966,7 +966,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../src ../README.md
+INPUT                  = ../src ../README.md namespace_docs.dox
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1071,7 +1071,8 @@ RECURSIVE              = YES
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = ../src/iceberg/test \
+                         ../src/iceberg/catalog/hive/gen-cpp
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -1087,7 +1088,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = *_internal.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

mkdocs/build-docs.sh

@@ -41,6 +41,7 @@ if ! command -v doxygen &> /dev/null; then
 else
     echo "Building API documentation with Doxygen..."
     cd mkdocs
+    rm -rf docs/api
     mkdir -p docs/api
     doxygen Doxyfile
     cd ..

mkdocs/namespace_docs.dox

@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+
+/// \namespace iceberg
+/// \brief Core Apache Iceberg C++ APIs.
+
+/// \namespace iceberg::arrow
+/// \brief Arrow-backed IO and data conversion APIs.
+
+/// \namespace iceberg::avro
+/// \brief Avro reader, writer, and metadata APIs.
+
+/// \namespace iceberg::hive
+/// \brief Hive catalog APIs.
+
+/// \namespace iceberg::parquet
+/// \brief Parquet reader, writer, and registration APIs.
+
+/// \namespace iceberg::puffin
+/// \brief Puffin file metadata, reader, and writer APIs.
+
+/// \namespace iceberg::rest
+/// \brief REST catalog APIs.
+
+/// \namespace iceberg::rest::auth
+/// \brief REST catalog authentication APIs.
+
+/// \namespace iceberg::retry
+/// \brief Retry policy APIs.
+
+/// \namespace iceberg::sql
+/// \brief SQL catalog APIs.
+
+/// \namespace iceberg::table
+/// \brief Table update requirement APIs.
+
+/// \namespace iceberg::util
+/// \brief Utility APIs.

src/iceberg/arrow/arrow_io_util.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/arrow/arrow_io_util.h
+/// \brief Provide helpers to create Arrow-backed FileIO implementations.
+
 #include <memory>
 #include <string>
 #include <unordered_map>

src/iceberg/arrow/s3/s3_properties.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/arrow/s3/s3_properties.h
+/// \brief Define S3 configuration property keys.
+
 #include <string_view>
 
 namespace iceberg::arrow {

src/iceberg/avro/avro_constants.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/avro/avro_constants.h
+/// \brief Define Avro metadata constants used by Iceberg.
+
 #include <string_view>
 
 namespace iceberg::avro {

src/iceberg/avro/avro_metrics.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/avro/avro_metrics.h
+/// \brief Compute Iceberg metrics for Avro data files.
+
 #include "iceberg/iceberg_bundle_export.h"
 #include "iceberg/metrics.h"
 

src/iceberg/avro/avro_reader.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/avro/avro_reader.h
+/// \brief Provide the Avro file reader interface.
+
 #include "iceberg/file_reader.h"
 #include "iceberg/iceberg_bundle_export.h"
 

src/iceberg/avro/avro_writer.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/avro/avro_writer.h
+/// \brief Provide the Avro file writer interface.
+
 #include "iceberg/file_writer.h"
 #include "iceberg/iceberg_bundle_export.h"
 

src/iceberg/catalog.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog.h
+/// \brief Define the catalog API for table and namespace operations.
+
 #include <memory>
 #include <string>
 #include <string_view>

src/iceberg/catalog/hive/iceberg_hive_export.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/hive/iceberg_hive_export.h
+/// \brief Define symbol visibility macros for the Hive catalog library.
+
 #if defined(_WIN32) || defined(__CYGWIN__)
 #  ifdef ICEBERG_HIVE_STATIC
 #    define ICEBERG_HIVE_EXPORT

src/iceberg/catalog/memory/in_memory_catalog.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/memory/in_memory_catalog.h
+/// \brief Provide an in-memory catalog implementation.
+
 #include <shared_mutex>
 
 #include "iceberg/catalog.h"

src/iceberg/catalog/rest/http_request.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/rest/http_request.h
+/// \brief Define REST HTTP request types.
+
 #include <algorithm>
 #include <cctype>
 #include <cstddef>

src/iceberg/catalog/rest/iceberg_rest_export.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/rest/iceberg_rest_export.h
+/// \brief Define symbol visibility macros for the REST catalog library.
+
 #if defined(_WIN32) || defined(__CYGWIN__)
 #  ifdef ICEBERG_REST_STATIC
 #    define ICEBERG_REST_EXPORT

src/iceberg/catalog/rest/rest_file_io.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/rest/rest_file_io.h
+/// \brief Provide helpers to create FileIO instances for REST catalog responses.
+
 #include <cstdint>
 #include <memory>
 #include <string_view>

src/iceberg/catalog/rest/rest_util.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/rest/rest_util.h
+/// \brief Provide utilities for REST catalog path and config handling.
+
 #include <string>
 #include <string_view>
 #include <unordered_map>

src/iceberg/catalog/session_catalog.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/session_catalog.h
+/// \brief Define session catalog routing APIs.
+
 #include <memory>
 #include <string_view>
 

src/iceberg/catalog/session_context.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/session_context.h
+/// \brief Define session context metadata.
+
 #include <string>
 #include <unordered_map>
 

src/iceberg/catalog/sql/iceberg_sql_catalog_export.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/catalog/sql/iceberg_sql_catalog_export.h
+/// \brief Define symbol visibility macros for the SQL catalog library.
+
 #if defined(_WIN32) || defined(__CYGWIN__)
 #  ifdef ICEBERG_SQL_CATALOG_STATIC
 #    define ICEBERG_SQL_CATALOG_EXPORT

src/iceberg/deletes/position_delete_range_consumer.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/deletes/position_delete_range_consumer.h
+/// \brief Provide bulk application of position deletes.
+
 #include <cstdint>
 #include <span>
 #include <vector>

src/iceberg/expression/literal.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/expression/literal.h
+/// \brief Define typed literal values used by expressions.
+
 #include <compare>
 #include <memory>
 #include <string>

src/iceberg/file_io.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/file_io.h
+/// \brief Define the FileIO abstraction and file stream interfaces.
+
 #include <cstddef>
 #include <cstdint>
 #include <memory>

src/iceberg/file_io_registry.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/file_io_registry.h
+/// \brief Define the FileIO registry.
+
 #include <functional>
 #include <memory>
 #include <string>

src/iceberg/iceberg_bundle_export.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/iceberg_bundle_export.h
+/// \brief Define symbol visibility macros for bundled format integrations.
+
 #if defined(_WIN32) || defined(__CYGWIN__)
 #  ifdef ICEBERG_BUNDLE_STATIC
 #    define ICEBERG_BUNDLE_EXPORT

src/iceberg/iceberg_data_export.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/iceberg_data_export.h
+/// \brief Define symbol visibility macros for data APIs.
+
 #if defined(_WIN32) || defined(__CYGWIN__)
 #  ifdef ICEBERG_DATA_STATIC
 #    define ICEBERG_DATA_EXPORT

src/iceberg/iceberg_export.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/iceberg_export.h
+/// \brief Define symbol visibility macros for core Iceberg APIs.
+
 #if defined(_WIN32) || defined(__CYGWIN__)
 #  ifdef ICEBERG_STATIC
 #    define ICEBERG_EXPORT

src/iceberg/inspect/history_table.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/inspect/history_table.h
+/// \brief Define the history metadata table.
+
 #include <memory>
 
 #include "iceberg/iceberg_export.h"

src/iceberg/inspect/metadata_table.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/inspect/metadata_table.h
+/// \brief Define base APIs for metadata tables.
+
 #include <memory>
 
 #include "iceberg/iceberg_export.h"

src/iceberg/inspect/snapshots_table.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/inspect/snapshots_table.h
+/// \brief Define the snapshots metadata table.
+
 #include <memory>
 
 #include "iceberg/iceberg_export.h"

src/iceberg/location_provider.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/location_provider.h
+/// \brief Define table data location providers.
+
 #include <memory>
 #include <string>
 #include <string_view>

src/iceberg/metrics/commit_report.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/metrics/commit_report.h
+/// \brief Define commit metrics and reports.
+
 #include <memory>
 #include <optional>
 #include <string>

src/iceberg/metrics/counter.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/metrics/counter.h
+/// \brief Define metrics counters.
+
 #include <atomic>
 #include <cstdint>
 #include <memory>

src/iceberg/metrics/metrics_reporter.h

@@ -19,6 +19,9 @@
 
 #pragma once
 
+/// \file iceberg/metrics/metrics_reporter.h
+/// \brief Define metrics report dispatch APIs.
+
 #include <string>
 #include <string_view>
 #include <unordered_map>