Skip to content

[SYCL][Doc] Update spec wording regarding C++20 #16713

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 23, 2025
Merged

[SYCL][Doc] Update spec wording regarding C++20 #16713

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions sycl/doc/extensions/proposed/sycl_ext_oneapi_device_image_backend_content.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,7 @@ class device_image {
backend ext_oneapi_get_backend() const noexcept;
std::vector<std::byte> ext_oneapi_get_backend_content() const;

#if defined(__cpp_lib_span)
std::span<std::byte> ext_oneapi_get_backend_content_view() const;
#endif
std::span<std::byte> ext_oneapi_get_backend_content_view() const; // Requires C++20

/*...*/
};
Expand Down Expand Up @@ -154,8 +152,7 @@ std::span<std::byte> ext_oneapi_get_content_backend_view() const;
----
!====

Available only when the compiler defines the `__cpp_lib_span` feature-test macro
(which is defined in {cpp}20 and higher).
Minimum C++ Version: {cpp}20
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this be in italics?

Suggested change
Minimum C++ Version: {cpp}20
_Minimum C++ Version:_ {cpp}20

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking it would not be in italics. In the core SYCL spec, our style is to add an initial paragraph for APIs that are deprecated, and that initial paragraph is not in italics. For example:

.[apidef]#platform::has_extension#
[source,role=synopsis,id=api:platform-has-extension]
----
bool has_extension(const std::string& extension) const
----

Deprecated by SYCL 2020.

{note}Use [api]#platform::has# instead.
{endnote}

_Returns:_ The value [code]#true# if this platform supports the extension
queried by the [code]#extension# parameter.
A platform only supports an extension if all associated devices support that
extension.
Returns [code]#false# if this platform does not contain any devices.

My thought was that the "Minimum C++ version" paragraph would be similar to the "Deprecated by" paragraph.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see. My preference here would be to adopt a consistent style for all paragraphs rather than mixing the old and new styles. I find the paragraph sub-headings really helpful when reading the specification, so something like a "Deprecated: SYCL 2020" looks better to me.

But I don't think we can solve this here, so I'll approve. But maybe we should talk to some other folks to see if anybody else has a preference either way.


_Constraints:_ Available only when `State` is `bundle_state::executable`.

Expand Down
Loading