From a0786adbc4e46520e2ac3b3d09e34dfaa489a845 Mon Sep 17 00:00:00 2001
From: Vincent Coubard <vincent.coubard@arm.com>
Date: Tue, 23 Oct 2018 11:38:01 +0100
Subject: [PATCH 1/4] Span: Improve documentation

Makes doxygen reference to SPAN_DYNAMIC_EXTENT by name instead of the macro expansion -1.
Add reference to the macro in the class documentation.
---
 platform/Span.h | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/platform/Span.h b/platform/Span.h
index 05c4ec0bcf1..d8386bf83fe 100644
--- a/platform/Span.h
+++ b/platform/Span.h
@@ -47,12 +47,18 @@ class is_convertible
 
 }
 
+#if defined(DOXYGEN_ONLY)
 /**
  * Special value for the Extent parameter of Span.
  * If the type uses this value, then the size of the array is stored in the object
  * at runtime.
+ * 
+ * @relates Span
  */
+const ptrdiff_t SPAN_DYNAMIC_EXTENT = -1;
+#else 
 #define SPAN_DYNAMIC_EXTENT -1
+#endif
 
 /**
  * Nonowning view to a sequence of contiguous elements.

From 03d308d114198da90583bdba9d53dbdcbdd0a171 Mon Sep 17 00:00:00 2001
From: Vincent Coubard <vincent.coubard@arm.com>
Date: Tue, 23 Oct 2018 11:38:37 +0100
Subject: [PATCH 2/4] Span: Add related non member function to class
 documentation.

---
 platform/Span.h | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/platform/Span.h b/platform/Span.h
index d8386bf83fe..c4d4362e696 100644
--- a/platform/Span.h
+++ b/platform/Span.h
@@ -780,6 +780,8 @@ struct Span<ElementType, SPAN_DYNAMIC_EXTENT> {
  *
  * @return True if Spans in input have the same size and the same content and
  * false otherwise.
+ * 
+ * @relates Span
  */
 template<typename T, typename U, ptrdiff_t LhsExtent, ptrdiff_t RhsExtent>
 bool operator==(const Span<T, LhsExtent> &lhs, const Span<U, RhsExtent> &rhs)
@@ -833,6 +835,8 @@ bool operator==(T (&lhs)[LhsExtent], const Span<T, RhsExtent> &rhs)
  *
  * @return True if arrays in input do not have the same size or the same content
  * and false otherwise.
+ * 
+ * @relates Span
  */
 template<typename T, typename U, ptrdiff_t LhsExtent, ptrdiff_t RhsExtent>
 bool operator!=(const Span<T, LhsExtent> &lhs, const Span<U, RhsExtent> &rhs)
@@ -882,6 +886,8 @@ bool operator!=(T (&lhs)[LhsExtent], const Span<T, RhsExtent> &rhs)
  *
  * @note This helper avoids the typing of template parameter when Span is
  * created 'inline'.
+ * 
+ * @relates Span
  */
 template<typename T, size_t Size>
 Span<T, Size> make_Span(T (&elements)[Size])
@@ -920,6 +926,8 @@ Span<T, Extent> make_Span(T *elements)
  *
  * @note This helper avoids the typing of template parameter when Span is
  * created 'inline'.
+ * 
+ * @relates Span
  */
 template<typename T>
 Span<T> make_Span(T *array_ptr, ptrdiff_t array_size)
@@ -957,6 +965,8 @@ Span<const T, Extent> make_const_Span(const T (&elements)[Extent])
  *
  * @note This helper avoids the typing of template parameter when Span is
  * created 'inline'.
+ * 
+ * @relates Span
  */
 template<size_t Extent, typename T>
 Span<const T, Extent> make_const_Span(const T *elements)
@@ -977,6 +987,8 @@ Span<const T, Extent> make_const_Span(const T *elements)
  *
  * @note This helper avoids the typing of template parameter when Span is
  * created 'inline'.
+ * 
+ * @relates Span
  */
 template<typename T>
 Span<const T> make_const_Span(T *array_ptr, size_t array_size)

From c956a93252599930b28e493329c3b6640cc2a34e Mon Sep 17 00:00:00 2001
From: Vincent Coubard <vincent.coubard@arm.com>
Date: Tue, 23 Oct 2018 11:39:27 +0100
Subject: [PATCH 3/4] Span: Improve subspan return type.

This clarifies code and documentation generated.
---
 platform/Span.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/platform/Span.h b/platform/Span.h
index c4d4362e696..cc5aff69303 100644
--- a/platform/Span.h
+++ b/platform/Span.h
@@ -697,7 +697,7 @@ struct Span<ElementType, SPAN_DYNAMIC_EXTENT> {
      * @return A subspan of this starting at Offset and Count long.
      */
     template<std::ptrdiff_t Offset, std::ptrdiff_t Count>
-    Span<element_type, Count == SPAN_DYNAMIC_EXTENT ? SPAN_DYNAMIC_EXTENT : Count>
+    Span<element_type, Count>
     subspan() const
     {
         MBED_ASSERT(0 <= Offset && Offset <= _size);
@@ -705,7 +705,7 @@ struct Span<ElementType, SPAN_DYNAMIC_EXTENT> {
             (Count == SPAN_DYNAMIC_EXTENT) ||
             (0 <= Count && (Count + Offset) <= _size)
         );
-        return Span<element_type, Count == SPAN_DYNAMIC_EXTENT ? SPAN_DYNAMIC_EXTENT : Count>(
+        return Span<element_type, Count>(
             _data + Offset,
             Count == SPAN_DYNAMIC_EXTENT ? _size - Offset : Count
         );

From 1e30ed599e517fee86b5ea8475564515643881b8 Mon Sep 17 00:00:00 2001
From: Vincent Coubard <vincent.coubard@arm.com>
Date: Tue, 23 Oct 2018 12:15:47 +0100
Subject: [PATCH 4/4] Span: define doc groups.

---
 platform/Span.h | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/platform/Span.h b/platform/Span.h
index cc5aff69303..f63a74309ed 100644
--- a/platform/Span.h
+++ b/platform/Span.h
@@ -25,6 +25,13 @@
 
 namespace mbed {
 
+/** \addtogroup platform */
+/** @{*/
+/**
+ * \defgroup platform_Span Span class
+ * @{
+ */
+
 // Internal details of Span
 // It is used construct Span from Span of convertible types (non const -> const)
 namespace span_detail {
@@ -996,6 +1003,10 @@ Span<const T> make_const_Span(T *array_ptr, size_t array_size)
     return Span<const T>(array_ptr, array_size);
 }
 
+/**@}*/
+
+/**@}*/
+
 } // namespace mbed
 
 #endif /* MBED_PLATFORM_SPAN_H_ */