Add decorators for registering benchmarks and adding axis

cuda.bench.register(fn) continues returning Benchmark, and supports
legacy use.

New signature added:
   cuda.bench.register():
      Returns a decorator

```
@bench.register()
@bench.axis.float64("Duration (s)", [7e-5, 1e-4, 5e-4])
@bench.option.min_samples(120)
def single_float64_axis(state: bench.State):
   ...
```

python/test/test_cuda_bench.py

@@ -1,4 +1,21 @@
+# Copyright 2026 NVIDIA Corporation
+#
+#  Licensed under the Apache License, Version 2.0 with the LLVM exception
+#  (the "License"); you may not use this file except in compliance with
+#  the License.
+#
+#  You may obtain a copy of the License at
+#
+#      http://llvm.org/foundation/relicensing/LICENSE.txt
+#
+#  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.
+
 import json
+from typing import Union
 
 import cuda.bench as bench
 import pytest
@@ -39,7 +56,7 @@ def test_cpu_only():
     bench.run_all_benchmarks(["-q", "--profile"])
 
 
-def docstring_check(doc_str: str) -> None:
+def docstring_check(doc_str: Union[str, None]) -> None:
     assert isinstance(doc_str, str)
     assert len(doc_str) > 0
 
@@ -56,6 +73,122 @@ def test_register_doc():
     obj_has_docstring_check(bench.register)
 
 
+def test_decorator_docstrings():
+    obj_has_docstring_check(bench.axis)
+    obj_has_docstring_check(bench.axis.int64)
+    obj_has_docstring_check(bench.axis.add_int64_axis)
+    obj_has_docstring_check(bench.axis.int64_power_of_two)
+    obj_has_docstring_check(bench.axis.power_of_two)
+    obj_has_docstring_check(bench.axis.add_int64_power_of_two_axis)
+    obj_has_docstring_check(bench.axis.float64)
+    obj_has_docstring_check(bench.axis.add_float64_axis)
+    obj_has_docstring_check(bench.axis.string)
+    obj_has_docstring_check(bench.axis.add_string_axis)
+
+    obj_has_docstring_check(bench.option)
+    obj_has_docstring_check(bench.option.name)
+    obj_has_docstring_check(bench.option.set_name)
+    obj_has_docstring_check(bench.option.run_once)
+    obj_has_docstring_check(bench.option.set_run_once)
+    obj_has_docstring_check(bench.option.skip_time)
+    obj_has_docstring_check(bench.option.set_skip_time)
+    obj_has_docstring_check(bench.option.throttle_recovery_delay)
+    obj_has_docstring_check(bench.option.set_throttle_recovery_delay)
+    obj_has_docstring_check(bench.option.throttle_threshold)
+    obj_has_docstring_check(bench.option.set_throttle_threshold)
+    obj_has_docstring_check(bench.option.timeout)
+    obj_has_docstring_check(bench.option.set_timeout)
+    obj_has_docstring_check(bench.option.stopping_criterion)
+    obj_has_docstring_check(bench.option.set_stopping_criterion)
+    obj_has_docstring_check(bench.option.criterion_param_float64)
+    obj_has_docstring_check(bench.option.set_criterion_param_float64)
+    obj_has_docstring_check(bench.option.criterion_param_int64)
+    obj_has_docstring_check(bench.option.set_criterion_param_int64)
+    obj_has_docstring_check(bench.option.criterion_param_string)
+    obj_has_docstring_check(bench.option.set_criterion_param_string)
+    obj_has_docstring_check(bench.option.min_samples)
+    obj_has_docstring_check(bench.option.set_min_samples)
+    obj_has_docstring_check(bench.option.is_cpu_only)
+    obj_has_docstring_check(bench.option.set_is_cpu_only)
+
+
+def test_register_decorator_preserves_function_and_applies_options(monkeypatch):
+    class FakeBenchmark:
+        def __init__(self):
+            self.calls = []
+
+        def add_int64_axis(self, name, values):
+            self.calls.append(("int64", name, list(values)))
+            return self
+
+        def set_min_samples(self, count):
+            self.calls.append(("min_samples", count))
+            return self
+
+    fake_benchmark = FakeBenchmark()
+    registered_functions = []
+
+    def fake_register(fn):
+        registered_functions.append(fn)
+        return fake_benchmark
+
+    monkeypatch.setattr(bench, "_register", fake_register)
+
+    @bench.register()
+    @bench.axis.int64("Elements", [1, 2, 3])
+    @bench.option.min_samples(11)
+    def decorated(state: bench.State):
+        pass
+
+    assert registered_functions == [decorated]
+    assert fake_benchmark.calls == [
+        ("int64", "Elements", [1, 2, 3]),
+        ("min_samples", 11),
+    ]
+    assert callable(decorated)
+
+
+def test_register_function_form_applies_decorated_options(monkeypatch):
+    class FakeBenchmark:
+        def __init__(self):
+            self.calls = []
+
+        def add_float64_axis(self, name, values):
+            self.calls.append(("float64", name, list(values)))
+            return self
+
+    fake_benchmark = FakeBenchmark()
+
+    def fake_register(fn):
+        return fake_benchmark
+
+    monkeypatch.setattr(bench, "_register", fake_register)
+
+    @bench.axis.float64("Duration", [0.1, 0.2])
+    def decorated(state: bench.State):
+        pass
+
+    assert bench.register(decorated) is fake_benchmark
+    assert fake_benchmark.calls == [("float64", "Duration", [0.1, 0.2])]
+
+
+def test_option_decorators_reject_wrong_order(monkeypatch):
+    class FakeBenchmark:
+        pass
+
+    def fake_register(fn):
+        return FakeBenchmark()
+
+    monkeypatch.setattr(bench, "_register", fake_register)
+
+    @bench.register()
+    def decorated(state: bench.State):
+        pass
+
+    with pytest.raises(RuntimeError, match="must be placed below"):
+        bench.option.min_samples(3)(decorated)
+
+
 def test_run_all_benchmarks_doc():
     obj_has_docstring_check(bench.run_all_benchmarks)