Improve the Guide's consistency of style by nnethercote · Pull Request #308 · Rust-GPU/rust-cuda

nnethercote · 2025-11-19T06:07:51Z

The Guide is very inconsistent on some matters of style: capitalization, use of backticks, and some word choices. Like a fine layer of grit over all the surfaces of a workshop, these low-level irritants get in the way of larger, more important changes. Let's fix them all now.

nnethercote · 2025-11-19T22:31:29Z

I fixed one more inconsistent capitalization case (nvidia/NVidia -> NVIDIA).

LegNeato

Just need to decide if we use code backtics for crate names. I think that is common practice and looks better but open for discussion.

LegNeato · 2025-11-21T05:19:16Z

guide/src/cuda/gpu_computing.md

-A couple of particular rust features make writing CUDA code much easier: RAII and Results.
-In `cust` everything uses RAII (through `Drop` impls) to manage freeing memory and returning handles, which 
+A couple of particular Rust features make writing CUDA code much easier: RAII and Results.
+In cust everything uses RAII (through `Drop` impls) to manage freeing memory and returning handles, which 


Suggested change

In cust everything uses RAII (through `Drop` impls) to manage freeing memory and returning handles, which

In `cust` everything uses RAII (through `Drop` impls) to manage freeing memory and returning handles, which

This should probably be code due to being a crate name? Not sure. Woul be good to link it too.

LegNeato · 2025-11-21T05:19:37Z

guide/src/cuda/gpu_computing.md


-Instead of an unreliable system of macros, we can leverage rust results for this. In cust we return special `CudaResult<T>`
-results that can be bubbled up using rust's `?` operator, or, similar to `CUDA_SAFE_CALL` can be unwrapped or expected if 
+Instead of an unreliable system of macros, we can leverage Rust results for this. In cust we return special `CudaResult<T>`


Suggested change

Instead of an unreliable system of macros, we can leverage Rust results for this. In cust we return special `CudaResult<T>`

Instead of an unreliable system of macros, we can leverage Rust results for this. In `cust` we return special `CudaResult<T>`

LegNeato · 2025-11-21T05:24:04Z

guide/src/guide/getting_started.md

+# Getting started

-This section covers how to get started writing GPU crates with `cuda_std` and `cuda_builder`.
+This section covers how to get started writing GPU crates with cuda_std and cuda_builder.


Same here, these are crate names which are usually marked as code?

Suggested change

This section covers how to get started writing GPU crates with cuda_std and cuda_builder.

This section covers how to get started writing GPU crates with `cuda_std` and `cuda_builder`.

LegNeato · 2025-11-21T05:24:27Z

guide/src/guide/getting_started.md

 ```

-Where `XX` is the latest version of `cuda_std`.
+Where `XX` is the latest version of cuda_std.


Suggested change

Where `XX` is the latest version of cuda_std.

Where `XX` is the latest version of `cuda_std`.

LegNeato · 2025-11-21T05:24:49Z

guide/src/guide/getting_started.md

 ```

-Finally, if you would like to use types such as slices or arrays inside of GPU kernels you must allow `improper_cytypes_definitions` either on the whole crate or the individual GPU kernels. This is because on the CPU, such types are not guaranteed to be passed a certain way, so they should not be used in `extern "C"` functions (which is what kernels are implicitly declared as). However, `rustc_codegen_nvvm` guarantees the way in which things like structs, slices, and arrays are passed. See [Kernel ABI](./kernel_abi.md).
+Finally, if you would like to use types such as slices or arrays inside of GPU kernels you must allow `improper_cytypes_definitions` either on the whole crate or the individual GPU kernels. This is because on the CPU, such types are not guaranteed to be passed a certain way, so they should not be used in `extern "C"` functions (which is what kernels are implicitly declared as). However, rustc_codegen_nvvm guarantees the way in which things like structs, slices, and arrays are passed. See [Kernel ABI](./kernel_abi.md).


Suggested change

Finally, if you would like to use types such as slices or arrays inside of GPU kernels you must allow `improper_cytypes_definitions` either on the whole crate or the individual GPU kernels. This is because on the CPU, such types are not guaranteed to be passed a certain way, so they should not be used in `extern "C"` functions (which is what kernels are implicitly declared as). However, rustc_codegen_nvvm guarantees the way in which things like structs, slices, and arrays are passed. See [Kernel ABI](./kernel_abi.md).

Finally, if you would like to use types such as slices or arrays inside of GPU kernels you must allow `improper_cytypes_definitions` either on the whole crate or the individual GPU kernels. This is because on the CPU, such types are not guaranteed to be passed a certain way, so they should not be used in `extern "C"` functions (which is what kernels are implicitly declared as). However, `rustc_codegen_nvvm` guarantees the way in which things like structs, slices, and arrays are passed. See [Kernel ABI](./kernel_abi.md).

A little shorter and clearer.

The Guide is currently very inconsistent with capitalization of abbreviations. The general trend is towards lower-case for informal English, but for formal English (such as documentation) I think upper-case is still preferable. - gpu -> GPU - cuda/Cuda -> CUDA - rustacuda -> RustaCUDA - llvm -> LLVM - nvvm -> NVVM - ir -> IR - ptx -> PTX - libnvvm -> libNVVM - Optix/optix -> OptiX - SPIRV -> SPIR-V - cuBlas/cuRand -> cuBLAS/cuRAND - i (the pronoun!) -> I - TLDR -> TL;DR

A lot of names are used sometimes with backticks, sometimes without. This commit removes backticks where necessary for these: - rustc - rust-gpu (which will become "Rust GPU" in a subsequent commit) And adds backticks where necessary for these: - rustc_codegen_* - cuda_builder - cuda_std - lib.rs

- Rustc -> rustc (truly!) - rust -> Rust - NVidia/nvidia -> NVIDIA

[I accidentally squashed two commits, and can't be bothered separating them.] The existing text uses "codegen" frequently as a shorthand for "codegen backend". I found this confusing and distracting. ("Codegens" is even worse.) This commit replaces these uses with "codegen backend" (or occasionally something else more appropriate). The commit preserves the use of "codegen" for the act of code generation, e.g. "during codegen we do XYZ", because that's more standard. Also, currently headings are a mix of sentence case ("The quick brown fox") and title case ("The Quick Brown Fox"). Title case is extremely formal, so sentence case feels more natural here.

nnethercote · 2025-11-21T10:48:55Z

Ok, I have updated to use backticks on crate names like cust, cuda_std, and rustc_codegen_*.

nnethercote changed the title ~~Improve the Guide~~ Improve the Guide's consistency of style Nov 19, 2025

nnethercote requested a review from LegNeato November 19, 2025 06:09

nnethercote force-pushed the guide-grit branch from dab15bd to f1df692 Compare November 19, 2025 22:30

LegNeato requested changes Nov 21, 2025

View reviewed changes

nnethercote added 7 commits November 21, 2025 20:58

Use "Rust CUDA" for the project name consistently.

1450e50

Change the guide title and description.

cb2956f

A little shorter and clearer.

Use consistent capitalization, part 2.

9209ede

- Rustc -> rustc (truly!) - rust -> Rust - NVidia/nvidia -> NVIDIA

Use "Rust GPU" for the project name consistently.

227d660

nnethercote force-pushed the guide-grit branch from f1df692 to 8bc37a6 Compare November 21, 2025 10:48

nnethercote requested a review from LegNeato November 21, 2025 10:48

LegNeato approved these changes Nov 22, 2025

View reviewed changes

LegNeato merged commit d8cf0b9 into Rust-GPU:main Nov 22, 2025
17 of 18 checks passed

nnethercote deleted the guide-grit branch November 23, 2025 20:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the Guide's consistency of style#308

Improve the Guide's consistency of style#308
LegNeato merged 7 commits intoRust-GPU:mainfrom
nnethercote:guide-grit

nnethercote commented Nov 19, 2025 •

edited

Loading

Uh oh!

nnethercote commented Nov 19, 2025

Uh oh!

LegNeato left a comment

Uh oh!

LegNeato Nov 21, 2025

Uh oh!

LegNeato Nov 21, 2025

Uh oh!

LegNeato Nov 21, 2025

Uh oh!

LegNeato Nov 21, 2025

Uh oh!

LegNeato Nov 21, 2025

Uh oh!

nnethercote commented Nov 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	In cust everything uses RAII (through `Drop` impls) to manage freeing memory and returning handles, which
	In `cust` everything uses RAII (through `Drop` impls) to manage freeing memory and returning handles, which

	Instead of an unreliable system of macros, we can leverage Rust results for this. In cust we return special `CudaResult<T>`
	Instead of an unreliable system of macros, we can leverage Rust results for this. In `cust` we return special `CudaResult<T>`

	This section covers how to get started writing GPU crates with cuda_std and cuda_builder.
	This section covers how to get started writing GPU crates with `cuda_std` and `cuda_builder`.

	Where `XX` is the latest version of cuda_std.
	Where `XX` is the latest version of `cuda_std`.

Conversation

nnethercote commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nnethercote commented Nov 19, 2025

Uh oh!

LegNeato left a comment

Choose a reason for hiding this comment

Uh oh!

LegNeato Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

LegNeato Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

LegNeato Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

LegNeato Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

LegNeato Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

nnethercote commented Nov 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

nnethercote commented Nov 19, 2025 •

edited

Loading