fix: generate public API docs correctly (#804)

Author: zhjwpku

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
@@ -1006,57 +1006,9 @@ INPUT_FILE_ENCODING    =
 # be provided as doxygen C comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
 # *.f18, *.f, *.for, *.vhd, *.vhdl, *.ucf, *.qsf and *.ice.
 
-FILE_PATTERNS          = *.c \
-                         *.cc \
-                         *.cxx \
-                         *.cxxm \
-                         *.cpp \
-                         *.cppm \
-                         *.ccm \
-                         *.c++ \
-                         *.c++m \
-                         *.java \
-                         *.ii \
-                         *.ixx \
-                         *.ipp \
-                         *.i++ \
-                         *.inl \
-                         *.idl \
-                         *.ddl \
-                         *.odl \
-                         *.h \
-                         *.hh \
-                         *.hxx \
-                         *.hpp \
-                         *.h++ \
-                         *.ixx \
-                         *.l \
-                         *.cs \
-                         *.d \
-                         *.php \
-                         *.php4 \
-                         *.php5 \
-                         *.phtml \
-                         *.inc \
-                         *.m \
-                         *.markdown \
+FILE_PATTERNS          = *.h \
                          *.md \
-                         *.mm \
-                         *.dox \
-                         *.py \
-                         *.pyw \
-                         *.f90 \
-                         *.f95 \
-                         *.f03 \
-                         *.f08 \
-                         *.f18 \
-                         *.f \
-                         *.for \
-                         *.vhd \
-                         *.vhdl \
-                         *.ucf \
-                         *.qsf \
-                         *.ice
+                         *.dox
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
@@ -1071,7 +1023,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 +1040,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"