[gcc/devel/rust/master] libproc_macro: Add documentation to interface

[gcc/devel/rust/master] libproc_macro: Add documentation to interface

[Thomas Schwinge]

https://gcc.gnu.org/g:a4b7fca1ec1d2a1b9f416cbefc7a2dcd6f3935f3

commit a4b7fca1ec1d2a1b9f416cbefc7a2dcd6f3935f3
Author: Pierre-Emmanuel Patry <pierre-emmanuel.patry@embecosm.com>
Date:   Mon Feb 13 12:21:13 2023 +0100

    libproc_macro: Add documentation to interface
    
    Add some string documentation to existing rust type interface.
    
    ChangeLog:
    
            * librust/proc_macro/rust/ident.rs: Add documentation.
            * librust/proc_macro/rust/lib.rs: Add documentation.
            * librust/proc_macro/rust/literal.rs: Add documentation.
            * librust/proc_macro/rust/span.rs: Add documentation.
    
    Signed-off-by: Pierre-Emmanuel Patry <pierre-emmanuel.patry@embecosm.com>

Diff:
---
 librust/proc_macro/rust/ident.rs   | 35 ++++++++++++++++++++++++++++++-----
 librust/proc_macro/rust/lib.rs     |  7 ++++++-
 librust/proc_macro/rust/literal.rs | 22 ++++++++++++++++++++++
 librust/proc_macro/rust/span.rs    | 15 ++++++++++++---
 4 files changed, 70 insertions(+), 9 deletions(-)

diff --git a/librust/proc_macro/rust/ident.rs b/librust/proc_macro/rust/ident.rs
index f9bf8146762..5d21cbd498a 100644
--- a/librust/proc_macro/rust/ident.rs
+++ b/librust/proc_macro/rust/ident.rs
@@ -1,18 +1,40 @@
 use std::fmt;
 use Span;
 
+/// An identifier.
 #[derive(Clone)]
 pub struct Ident {
     // Internal implementation details
 }
 
 impl Ident {
-    /// Creates a new identifier from a string and a span
+    /// Creates a new identifier.
+    ///
+    /// # Arguments
+    ///
+    /// * `string` - A valid identifier.
+    /// * `span` - The span of the identifier.
+    ///
+    /// # Panics
+    ///
+    /// The `string` argument must be a valid identifier permitted by the
+    /// language, otherwise the function will panic.
     pub fn new(_string: &str, _span: Span) -> Self {
         todo!("Implement this function")
     }
 
-    /// Creates a raw new identifier from a string and a span
+    /// Creates a new raw identifier.
+    ///
+    /// # Arguments
+    ///
+    /// * `string` - A valid identifier.
+    /// * `span` - The span of the identifier.
+    ///
+    /// # Panics
+    ///
+    /// The `string` argument must be a valid identifier permitted by the
+    /// language. Furthermore, it should not be a keyword used in path
+    /// segments, otherwise this function will panic.
     pub fn new_raw(_string: &str, _span: Span) -> Self {
         todo!("Implement this function")
     }
@@ -22,21 +44,24 @@ impl Ident {
         todo!("Implement this function")
     }
 
-    /// change the span of the identifier
+    /// Change the span of the identifier.
+    ///
+    /// # Arguments
+    ///
+    /// * `span` - The new span value.
     pub fn set_span(&mut self, _span: Span) {
         todo!("Implement this function")
     }
 }
 
 impl fmt::Display for Ident {
-    /// Display as lossless converted string
+    /// Display as lossless converted string.
     fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result {
         todo!("Implement this function")
     }
 }
 
 impl fmt::Debug for Ident {
-    /// display debug friendly version of the Identifier
     fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result {
         todo!("Implement this function")
     }
diff --git a/librust/proc_macro/rust/lib.rs b/librust/proc_macro/rust/lib.rs
index f79342e522b..fa1160ef60f 100644
--- a/librust/proc_macro/rust/lib.rs
+++ b/librust/proc_macro/rust/lib.rs
@@ -10,15 +10,20 @@ mod literal;
 mod punct;
 mod span;
 
+/// Describes how a sequence of token trees is delimited.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum Delimiter {
+    /// The sequence is delimited by a parentheses `(...)`.
     Parenthesis,
+    /// The sequence is delimited by a brace `{...}`.
     Brace,
+    /// The sequence is delimited by a bracket `[...]`.
     Bracket,
-    /// Invisible delimiter
+    /// Invisible delimiter to preserve operator priority.
     None,
 }
 
+/// Error returned from `from_str` functions.
 #[derive(Debug)]
 pub struct LexError;
 
diff --git a/librust/proc_macro/rust/literal.rs b/librust/proc_macro/rust/literal.rs
index 515c7d2737a..93d9b76ead6 100644
--- a/librust/proc_macro/rust/literal.rs
+++ b/librust/proc_macro/rust/literal.rs
@@ -3,6 +3,22 @@ use std::str::FromStr;
 use LexError;
 use Span;
 
+/// A type representing a literal value except `true` and `false`.
+///
+/// This could be one of the following:
+/// * literal string (`"hello"`)
+/// * byte string (`b"hello"`)
+/// * character (`'a'`)
+/// * byte character (`b'a'`)
+/// * unsuffixed integer (`42`)
+/// * suffixed integer (`42u8`)
+/// * unsuffixed floating point number (`1.618`)
+/// * suffixed floating point number (`1.618f32`)
+///
+/// # Note
+///
+/// Boolean literals like `true` and `false` are `Ident`s and do not belong
+/// here.
 #[derive(Clone)]
 pub struct Literal {
     // Internal implementation details
@@ -137,10 +153,16 @@ impl Literal {
         todo!("Implement this function")
     }
 
+    /// Get the [`Span`] for this literal.
     pub fn span(&self) -> Span {
         todo!("Get the span of a literal")
     }
 
+    /// Set the span for this literal.
+    ///
+    /// # Arguments
+    ///
+    /// * `span` - The new span value.
     pub fn set_span(&mut self, _span: Span) {
         todo!("Set the span of a literal")
     }
diff --git a/librust/proc_macro/rust/span.rs b/librust/proc_macro/rust/span.rs
index 646e35c356a..b1c51d2c07e 100644
--- a/librust/proc_macro/rust/span.rs
+++ b/librust/proc_macro/rust/span.rs
@@ -1,5 +1,6 @@
 use std::fmt;
 
+/// A region of source code along with macro expansion information.
 #[derive(Copy, Clone)]
 pub struct Span {
     // Internal implementation details
@@ -8,25 +9,33 @@ pub struct Span {
 impl Span {
     // TODO: Add experimental API functions for this type
 
-    /// Creates a new span that resolves at the macro call location
+    /// Creates a new span that resolves at the macro call location.
     pub fn call_site() -> Self {
         todo!("Implement this function")
     }
 
     /// Creates a new span that resolved sometimes at macro call site, and
-    /// sometimes at macro definition site
+    /// sometimes at macro definition site.
     pub fn mixed_site() -> Self {
         todo!("Implement this function")
     }
 
     /// Creates a new span with the same line/column informations but that
-    /// resolve symbols as though it were at `other`
+    /// resolve symbols as though it were at `other`.
+    ///
+    /// # Arguments
+    ///
+    /// * `other` - Other span to resolve at.
     pub fn resolved_at(&self, _other: Span) -> Self {
         todo!("Implement this function")
     }
 
     /// Creates a new span with the same name resolution behavior as self, but
     /// with the line/column information of `other`.
+    ///
+    /// # Arguments
+    ///
+    /// * `other` - Other span containing the line/column informations to use.
     pub fn located_at(&self, _other: Span) -> Self {
         todo!("Implement this function")
     }