This is an automated email from the ASF dual-hosted git repository.
pitrou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/main by this push:
new e2524aa088c MINOR: [Format] Fix docstrings in .fbs (#50826)
e2524aa088c is described below
commit e2524aa088cd6a391b40635245d757542e2b2810
Author: Emil Ernerfeldt <[email protected]>
AuthorDate: Tue Aug 25 01:38:34 2026 -0700
MINOR: [Format] Fix docstrings in .fbs (#50826)
### Rationale for this change
I noticed that `LZ4_FRAME` [lacks docs in
arrow-rs](https://docs.rs/arrow-ipc/latest/arrow_ipc/gen/Message/struct.CompressionType.html#associatedconstant.LZ4_FRAME)
and traced it back to a mistaken use of `//` (comment) instead of `///`
(docstring) in a .fbs file. I decided to fix the other suspected mistakes too.
### Are these changes tested?
Generated Rust with `flatc 23.5.26` before and after and diffed. The only
differences are the new doc comment blocks.
### Are there any user-facing changes?
Yes! There are now docstrings in the generated code :)
---
Disclosure per the [AI-generated code
guidance](https://arrow.apache.org/docs/dev/developers/overview.html#ai-generated-code):
I used Claude Code to find the affected comments and verify the
generated-output diff. I reviewed every line.
Lead-authored-by: Emil Ernerfeldt <[email protected]>
Co-authored-by: Emil Ernerfeldt <[email protected]>
Co-authored-by: Antoine Pitrou <[email protected]>
Signed-off-by: Antoine Pitrou <[email protected]>
---
format/Message.fbs | 8 +++---
format/Schema.fbs | 77 ++++++++++++++++++++++++++++++------------------------
2 files changed, 47 insertions(+), 38 deletions(-)
diff --git a/format/Message.fbs b/format/Message.fbs
index 6361a38245a..d4b6c0bb99e 100644
--- a/format/Message.fbs
+++ b/format/Message.fbs
@@ -43,12 +43,12 @@ struct FieldNode {
}
enum CompressionType: byte {
- // LZ4 frame format, for portability, as provided by lz4frame.h or wrappers
- // thereof. Not to be confused with "raw" (also called "block") format
- // provided by lz4.h
+ /// LZ4 frame format, for portability, as provided by lz4frame.h or wrappers
+ /// thereof. Not to be confused with "raw" (also called "block") format
+ /// provided by lz4.h
LZ4_FRAME,
- // Zstandard
+ /// Zstandard
ZSTD
}
diff --git a/format/Schema.fbs b/format/Schema.fbs
index 933b7696e29..67b77191282 100644
--- a/format/Schema.fbs
+++ b/format/Schema.fbs
@@ -395,42 +395,50 @@ table Timestamp {
timezone: string;
}
-enum IntervalUnit: short { YEAR_MONTH, DAY_TIME, MONTH_DAY_NANO}
-// A "calendar" interval which models types that don't necessarily
-// have a precise duration without the context of a base timestamp (e.g.
-// days can differ in length during day light savings time transitions).
-// All integers in the types below are stored in the endianness indicated
-// by the schema.
-//
-// YEAR_MONTH - Indicates the number of elapsed whole months, stored as
-// 4-byte signed integers.
-// DAY_TIME - Indicates the number of elapsed days and milliseconds (no leap
seconds),
-// stored as 2 contiguous 32-bit signed integers (8-bytes in total). Support
-// of this IntervalUnit is not required for full arrow compatibility.
-// MONTH_DAY_NANO - A triple of the number of elapsed months, days, and
nanoseconds.
-// The values are stored contiguously in 16-byte blocks. Months and days are
-// encoded as 32-bit signed integers and nanoseconds is encoded as a 64-bit
-// signed integer. Nanoseconds does not allow for leap seconds. Each field is
-// independent (e.g. there is no constraint that nanoseconds have the same
-// sign as days or that the quantity of nanoseconds represents less than a
-// day's worth of time).
+/// The unit of an Interval.
+///
+/// All integers in the units below are stored in the endianness indicated
+/// by the schema.
+enum IntervalUnit: short {
+ /// Indicates the number of elapsed whole months, stored as
+ /// 4-byte signed integers.
+ YEAR_MONTH,
+
+ /// Indicates the number of elapsed days and milliseconds (no leap seconds),
+ /// stored as 2 contiguous 32-bit signed integers (8-bytes in total). Support
+ /// of this IntervalUnit is not required for full Arrow compatibility.
+ DAY_TIME,
+
+ /// A triple of the number of elapsed months, days, and nanoseconds.
+ /// The values are stored contiguously in 16-byte blocks. Months and days are
+ /// encoded as 32-bit signed integers and nanoseconds is encoded as a 64-bit
+ /// signed integer. Nanoseconds does not allow for leap seconds. Each field
is
+ /// independent (e.g. there is no constraint that nanoseconds have the same
+ /// sign as days or that the quantity of nanoseconds represents less than a
+ /// day's worth of time).
+ MONTH_DAY_NANO
+}
+
+/// A "calendar" interval which models types that don't necessarily
+/// have a precise duration without the context of a base timestamp (e.g.
+/// days can differ in length during day light savings time transitions).
table Interval {
unit: IntervalUnit;
}
-// An absolute length of time unrelated to any calendar artifacts.
-//
-// For the purposes of Arrow Implementations, adding this value to a Timestamp
-// ("t1") naively (i.e. simply summing the two numbers) is acceptable even
-// though in some cases the resulting Timestamp (t2) would not account for
-// leap-seconds during the elapsed time between "t1" and "t2". Similarly,
-// representing the difference between two Unix timestamps is acceptable, but
-// would yield a value that is possibly a few seconds off from the true elapsed
-// time.
-//
-// The resolution defaults to millisecond, but can be any of the other
-// supported TimeUnit values as with Timestamp and Time types. This type is
-// always represented as an 8-byte integer.
+/// An absolute length of time unrelated to any calendar artifacts.
+///
+/// For the purposes of Arrow Implementations, adding this value to a Timestamp
+/// ("t1") naively (i.e. simply summing the two numbers) is acceptable even
+/// though in some cases the resulting Timestamp (t2) would not account for
+/// leap-seconds during the elapsed time between "t1" and "t2". Similarly,
+/// representing the difference between two Unix timestamps is acceptable, but
+/// would yield a value that is possibly a few seconds off from the true
elapsed
+/// time.
+///
+/// The resolution defaults to millisecond, but can be any of the other
+/// supported TimeUnit values as with Timestamp and Time types. This type is
+/// always represented as an 8-byte integer.
table Duration {
unit: TimeUnit = MILLISECOND;
}
@@ -469,7 +477,7 @@ union Type {
}
/// ----------------------------------------------------------------------
-/// user defined key value pairs to add custom metadata to arrow
+/// user defined key value pairs to add custom metadata to Arrow
/// key namespacing is the responsibility of the user
table KeyValue {
@@ -561,7 +569,8 @@ table Schema {
endianness: Endianness=Little;
fields: [Field];
- // User-defined metadata
+
+ /// User-defined metadata
custom_metadata: [ KeyValue ];
/// Features used in the stream/file.
