From ce6689da10bc6544b923d73427c8acbd8a92333d Mon Sep 17 00:00:00 2001
From: Trevor Keegan <44409350+inquisitev@users.noreply.github.com>
Date: Fri, 22 Sep 2023 06:25:07 -0500
Subject: [PATCH] standardize since tags (#373)

Standardizes all doxygen `@since` tags to use the same format of
"release vx.x.x", and adds a continuous integration script to
identify any future deviations.

This fixes #372, which can be referenced for further information.
---
 .github/workflows/analysis.yml                | 24 ++++++++++++++++
 ChangeLog.md                                  |  4 +--
 include/private/config/journald_supported.h   |  4 +--
 include/private/error.h                       |  2 +-
 include/private/target/journald.h             | 28 +++++++++----------
 include/stumpless/config/journald_supported.h |  8 +++---
 include/stumpless/element.h                   |  2 +-
 include/stumpless/entry.h                     |  4 +--
 include/stumpless/error.h                     |  4 +--
 include/stumpless/param.h                     |  2 +-
 include/stumpless/target.h                    |  4 +--
 include/stumpless/target/function.h           |  4 +--
 include/stumpless/target/journald.h           |  8 +++---
 13 files changed, 61 insertions(+), 37 deletions(-)

diff --git a/.github/workflows/analysis.yml b/.github/workflows/analysis.yml
index 83a136b96..f26ff618f 100644
--- a/.github/workflows/analysis.yml
+++ b/.github/workflows/analysis.yml
@@ -70,3 +70,27 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
           SONARQUBE_SCANNER_PARAMS: '{"sonar.host.url":"https://sonarcloud.io"}'
+  custom-anaysis:
+    name: Custom Analysis
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: "@since standardization"
+        run: |
+          # look for all instances of @since, then look for any that do not meet the required pattern. @since release x.x.x
+          if grep --include=\*.{c,h,cpp,hpp} -rnw . -e ".*@since .*" | grep -qv ".* @since release v[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]].*"; then
+            # at this point the check has failed, but we want to give some info to the user. i have found it difficult to get the status code
+            # and print out the offending lines without this duplication
+            # get all instances of @since, offending and not offending
+            grep --include=\*.{c,h,cpp,hpp} -rnw . -e "@since .*" | \
+            # find all instances that do not meet the required pattern
+            grep -v ".* @since release v[[:digit:]]\+\.[[:digit:]]\+\.[[:digit:]].*" | \
+            # print an error message, including line number with -n from grep. mention supported format. 
+            xargs -I{} echo "Static Analysis Failed:     \"{}\"      Supported format is \"@since release vX.X.X\""
+            exit 1
+          else
+            exit 0
+          fi
+
diff --git a/ChangeLog.md b/ChangeLog.md
index 76cb6ebf8..ec5ab6617 100644
--- a/ChangeLog.md
+++ b/ChangeLog.md
@@ -4,13 +4,13 @@ All notable changes to stumpless will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
 For a detailed look at the project's future, including planned features and bug
 fixes, check out the
 [roadmap](https://github.com/goatshriek/stumpless/blob/master/docs/roadmap.md).
 
-
 ## [2.2.0] - 2023-08-08
+### Added 
+ - @since format check enforcement in CI pipeline.
 ### Fixed
  - Deadlock potential in `stumpless_set_entry_hostname` and
    `stumpless_set_entry_procid` when validation fails.
diff --git a/include/private/config/journald_supported.h b/include/private/config/journald_supported.h
index 74103cc25..f21da3683 100644
--- a/include/private/config/journald_supported.h
+++ b/include/private/config/journald_supported.h
@@ -36,7 +36,7 @@
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param element The element to initialize.
  */
@@ -57,7 +57,7 @@ journald_init_journald_element( struct stumpless_element *element );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param param The param to initialize.
  */
diff --git a/include/private/error.h b/include/private/error.h
index 8c17f311a..90f1cd2a1 100644
--- a/include/private/error.h
+++ b/include/private/error.h
@@ -317,7 +317,7 @@ raise_windows_failure( const char *message, int code, const char *code_type );
  * cancelled, as the lock used to control access to the error stream may not
  * be released after a cancellation.
  *
- * @since v2.1.0.
+ * @since release v2.1.0.
  *
  * @param msg The message to be written to the error stream.
  *
diff --git a/include/private/target/journald.h b/include/private/target/journald.h
index d098e4676..4bd38cded 100644
--- a/include/private/target/journald.h
+++ b/include/private/target/journald.h
@@ -37,7 +37,7 @@
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param flattened A buffer to write the flattened name to.
  *
@@ -65,7 +65,7 @@ get_journald_field_name( char *flattened, const char *raw, size_t size );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param field_count The number of fields the buffer must have.
  */
@@ -87,7 +87,7 @@ init_fields( size_t field_count );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  */
 void
 init_fixed_fields( void );
@@ -107,7 +107,7 @@ init_fixed_fields( void );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory deallocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  */
 void
 journald_free_thread( void );
@@ -127,7 +127,7 @@ journald_free_thread( void );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the facility from.
  */
@@ -149,7 +149,7 @@ load_facility( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the identifier from.
  */
@@ -171,7 +171,7 @@ load_identifier( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the message from.
  *
@@ -196,7 +196,7 @@ load_message( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the msgid from.
  */
@@ -215,7 +215,7 @@ load_msgid( const struct stumpless_entry *entry );
  * **Async Cancel Safety: AC-Safe**
  * Logging to journald targets is async cancellation safe.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @return The size of the loaded pid, including the field prefix.
  */
@@ -237,7 +237,7 @@ load_pid( void );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the priority from.
  */
@@ -260,7 +260,7 @@ load_priority( const struct stumpless_entry *entry );
  * Logging to journald targets is not async cancellation safe as it uses locks
  * that may not be released if a thread is cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry to load the fields from.
  *
@@ -284,7 +284,7 @@ load_sd_fields( const struct stumpless_entry *entry );
  * **Async Cancel Safety: AC-Safe**
  * Logging to journald targets is async cancellation safe.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @return The size of the loaded timestamp, including the field prefix.
  */
@@ -305,7 +305,7 @@ load_timestamp( void );
  * Logging to journald targets is not async cancellation safe as it relies on
  * sd_journal_sendv which is not documented as such.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param target Where to send the entry.
  *
@@ -334,7 +334,7 @@ send_entry_to_journald_target( const struct stumpless_target *target,
  * This function is not async cancellation safe as it may leave the buffers in
  * an inconsistent state.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  */
 void
 set_field_bases( void );
diff --git a/include/stumpless/config/journald_supported.h b/include/stumpless/config/journald_supported.h
index 61b2b2f01..3bf1a6caa 100644
--- a/include/stumpless/config/journald_supported.h
+++ b/include/stumpless/config/journald_supported.h
@@ -48,7 +48,7 @@ extern "C" {
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param element The element to get the function of.
  *
@@ -76,7 +76,7 @@ stumpless_get_element_journald_namer( const struct stumpless_element *element );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param param The param to get the function of.
  *
@@ -104,7 +104,7 @@ stumpless_get_param_journald_namer( const struct stumpless_param *param );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param element The element to set the function of.
  *
@@ -134,7 +134,7 @@ stumpless_set_element_journald_namer( struct stumpless_element *element,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of a lock which could be left locked.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param param The param to set the function of.
  *
diff --git a/include/stumpless/element.h b/include/stumpless/element.h
index 3e9b913d3..d3f9674fd 100644
--- a/include/stumpless/element.h
+++ b/include/stumpless/element.h
@@ -61,7 +61,7 @@ struct stumpless_entry;
  * This function must be safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *
diff --git a/include/stumpless/entry.h b/include/stumpless/entry.h
index 5411ae9a2..a92587cd9 100644
--- a/include/stumpless/entry.h
+++ b/include/stumpless/entry.h
@@ -953,7 +953,7 @@ stumpless_load_entry( struct stumpless_entry *entry,
  * This function has the same behavior as stumpless_load_entry_str, except it
  * does not create a new entry, instead loading an existing struct.
  *
- * @since version v2.2.0
+ * @since release v2.2.0
  *
  * @param facility The facility code of the event this entry describes. This
  * should be a \c STUMPLESS_FACILITY value.
@@ -1056,7 +1056,7 @@ stumpless_new_entry( enum stumpless_facility facility,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, due to the use of memory management functions.
  *
- * @since version v2.1.0
+ * @since release v2.1.0
  *
  * @param facility The facility code of the event this entry describes. This
  * should be a \c STUMPLESS_FACILITY value.
diff --git a/include/stumpless/error.h b/include/stumpless/error.h
index bd5de14eb..1863cc8d0 100644
--- a/include/stumpless/error.h
+++ b/include/stumpless/error.h
@@ -208,7 +208,7 @@ stumpless_get_error( void );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since Release v1.5.0
+ * @since release v1.5.0
  *
  * @param err The error to get the id from. This must not be NULL.
  *
@@ -233,7 +233,7 @@ stumpless_get_error_id( const struct stumpless_error *err );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since Release v1.6.0
+ * @since release v1.6.0
  *
  * @param id The error id to get the error string from.
  *
diff --git a/include/stumpless/param.h b/include/stumpless/param.h
index 9082ef7d6..948614c70 100644
--- a/include/stumpless/param.h
+++ b/include/stumpless/param.h
@@ -59,7 +59,7 @@ struct stumpless_entry;
  * This function must be safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *
diff --git a/include/stumpless/target.h b/include/stumpless/target.h
index 9ec701adf..cd4801395 100644
--- a/include/stumpless/target.h
+++ b/include/stumpless/target.h
@@ -466,7 +466,7 @@ stumpless_close_target( struct stumpless_target *target );
  * This function is safe to call from threads that may be ansynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @return The current stream where messages are logged to on setting the
  * the CONS option.
@@ -811,7 +811,7 @@ stumpless_open_target( struct stumpless_target *target );
  * This function is safe to call from threads that may be ansynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param stream The stream to write logs to. If this is NULL then the messages
  *	intended for the console stream will be ignored.
diff --git a/include/stumpless/target/function.h b/include/stumpless/target/function.h
index 0193839cd..9350f994f 100644
--- a/include/stumpless/target/function.h
+++ b/include/stumpless/target/function.h
@@ -73,7 +73,7 @@ typedef int ( *stumpless_log_func_t )( const struct stumpless_target *,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory deallocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param target The function target to close.
  */
@@ -102,7 +102,7 @@ stumpless_close_function_target( const struct stumpless_target *target );
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param name The name of the logging target.
  *
diff --git a/include/stumpless/target/journald.h b/include/stumpless/target/journald.h
index 5387a747f..d25504c84 100644
--- a/include/stumpless/target/journald.h
+++ b/include/stumpless/target/journald.h
@@ -69,7 +69,7 @@ extern "C" {
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory deallocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param target The journald target to close.
  */
@@ -98,7 +98,7 @@ stumpless_close_journald_target( const struct stumpless_target *target );
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *
@@ -144,7 +144,7 @@ stumpless_flatten_element_name( const struct stumpless_entry *entry,
  * This function is safe to call from threads that may be asynchronously
  * cancelled.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param entry The entry that the param is part of.
  *
@@ -185,7 +185,7 @@ stumpless_flatten_param_name( const struct stumpless_entry *entry,
  * This function is not safe to call from threads that may be asynchronously
  * cancelled, as the memory allocation function may not be AC-Safe itself.
  *
- * @since v2.1.0
+ * @since release v2.1.0
  *
  * @param name The name of the logging target.
  *