Missing @since JavaDoc tags - no version tracking for API additions

## Description
No JavaDoc comments contain `@since` tags to indicate when methods, classes, or features were added. This makes it impossible for users to know which version introduced specific functionality, complicating API version management.

## Current State

### ❌ No @since Tags Anywhere
```bash
grep -rn "@since" src/main/java --include="*.java"
# Returns: 0 results
```

### ❌ No @version Tags
```bash
grep -rn "@version" src/main/java --include="*.java"
# Returns: 0 results
```

### ✅ Version in pom.xml
```xml
<version>1.31</version>
```

## Why @since Tags Matter

### 1. API Version Tracking

**Without @since:**
```java
/**
 * Validates that a string is not null, empty, or whitespace-only.
 */
public static String requireNonBlank(final String string, final String message) {
```

Users can't tell:
- When was this method added?
- Is it safe to use in my project (depends on jcommons 1.20)?
- Was this in the original release?

**With @since:**
```java
/**
 * Validates that a string is not null, empty, or whitespace-only.
 * 
 * @param string the string to validate
 * @param message the error message
 * @return the validated string
 * @throws IllegalArgumentException if the string is blank
 * @since 1.28
 */
public static String requireNonBlank(final String string, final String message) {
```

Now users know:
- Added in version 1.28
- Safe if depending on 1.28+
- Relatively recent addition

### 2. Deprecation Context

**Current deprecation:**
```java
@Deprecated(since = "1.22", forRemoval = true)
public static String toString(final Serializable serializable) {
```

But there's no `@since` showing when it was **added**:
- Was it added in 1.0 and deprecated in 1.22?
- Or added in 1.20 and deprecated in 1.22?
- How long was it supported?

**Better:**
```java
/**
 * @since 1.0
 * @deprecated since 1.22, scheduled for removal in 2.0
 */
@Deprecated(since = "1.22", forRemoval = true)
```

### 3. Migration Planning

Users upgrading from old versions need to know:
- "We're on jcommons 1.15, upgrading to 1.31"
- "What new APIs are available?"
- "Which methods didn't exist in 1.15?"

Without `@since`, they must:
- Read CHANGELOG (if accurate)
- Check Git history
- Trial and error

### 4. Documentation Quality

Major libraries use `@since`:
- **Spring Framework**: Every public API has `@since`
- **Apache Commons**: Comprehensive `@since` tags
- **Java Standard Library**: All APIs tagged

Example from Spring:
```java
/**
 * @since 5.0
 */
public interface WebFluxConfigurer {
```

Example from Java:
```java
/**
 * @since 1.8
 */
default void forEach(Consumer<? super T> action) {
```

### 5. IDE Integration

IDEs show `@since` in code completion:
- IntelliJ shows "Since: 1.28" in popup
- Eclipse displays version info
- Helps developers avoid newer APIs

## Impact
- **Severity:** Low-Medium
- **Type:** Documentation / API Management
- No way to track API additions
- Harder to plan version upgrades
- Unprofessional documentation
- Missing industry best practice

## Recommended Fix

### 1. Add @since to All Public APIs

**Classes:**
```java
/**
 * Utility class for SOAP operations.
 * 
 * @author sfloess
 * @since 1.0
 */
public final class SoapUtil {
```

**Methods (added in initial version):**
```java
/**
 * Sets the endpoint URL.
 * 
 * @param port the port
 * @param url the URL
 * @return the configured port
 * @since 1.0
 */
public static <T> T setUrl(final T port, final String url) {
```

**Methods (added later):**
```java
/**
 * Validates non-blank string.
 * 
 * @param string the string to validate
 * @return the validated string
 * @since 1.28
 */
public static String requireNonBlank(final String string) {
```

**New features:**
```java
/**
 * Record for SOAP service configuration.
 * 
 * @param service the SOAP service
 * @param portType the port type
 * @since 1.30
 */
public record SoapRecord<T>(Service service, Class<T> portType) {
```

### 2. Determine When Each API Was Added

**For existing APIs:**

Option A - Conservative (mark all as 1.0):
```java
/**
 * @since 1.0
 */
```

Option B - Research from Git:
```bash
# Find when file was added
git log --follow --format=%H --reverse -- src/main/java/org/flossware/jcommons/util/SoapUtil.java | head -1

# Find commit details
git show <commit-hash>

# Check tags at that time
git describe --tags <commit-hash>
```

Option C - Use CHANGELOG:
- Review CHANGELOG.md for "Added" sections
- Correlate features to versions

**For new APIs going forward:**
- Add `@since` with current version
- Document in CHANGELOG

### 3. Update CONTRIBUTING.md

Add to documentation standards:
```markdown
## JavaDoc Requirements

All public APIs must include:

### Classes
```java
/**
 * Brief description.
 * 
 * <p>Detailed description if needed.
 * 
 * @author Your Name
 * @since X.Y (version when class was added)
 */
public class MyClass {
```

### Methods
```java
/**
 * Brief description.
 * 
 * @param name description
 * @return description
 * @throws Exception description
 * @since X.Y (version when method was added)
 */
public void myMethod(String name) {
```

### Deprecations
```java
/**
 * @since X.Y (when it was added)
 * @deprecated since X.Z, use {@link #newMethod()} instead
 */
@Deprecated(since = "X.Z", forRemoval = true)
public void oldMethod() {
```
```

### 4. Add to Checkstyle

Enforce `@since` tags:
```xml
<module name="JavadocMethod">
    <property name="validateThrows" value="true"/>
    <property name="scope" value="public"/>
    <property name="allowMissingParamTags" value="false"/>
    <property name="allowMissingReturnTag" value="false"/>
    
</module>

<module name="JavadocType">
    <property name="scope" value="public"/>
    
</module>
```

Or use custom Checkstyle check:
```xml
<module name="RegexpSinglelineJava">
    <property name="format" value="^\s*public\s+(class|interface|enum|record)"/>
    <property name="message" value="Public types should have @since tag in JavaDoc"/>
</module>
```

### 5. Update maven-javadoc-plugin

Configure to validate `@since`:
```xml
<plugin>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.12.0</version>
    <configuration>
        <tags>
            <tag>
                <name>since</name>
                <placement>a</placement>
                <head>Since:</head>
            </tag>
        </tags>
        <show>public</show>
        <failOnWarnings>true</failOnWarnings>
    </configuration>
</plugin>
```

## Migration Strategy

### Phase 1: Existing Code (v1.32)
1. Mark all existing public APIs with `@since 1.0`
   - Conservative approach
   - Indicates "been there a while"
   - Better than nothing

2. For features clearly added recently:
   - Check Git history
   - Update with correct version
   - Examples: SoapRecord (added recently)

### Phase 2: New Code (v1.32+)
1. Require `@since` for all new public APIs
2. Use current version in development
3. Update during release if needed

### Phase 3: Enforcement (v2.0)
1. Enable Checkstyle validation
2. Fail build on missing `@since`
3. Make it impossible to forget

## Example Updates

### SoapUtil (exists since project start)
```java
/**
 * Utility class for Apache CXF SOAP service operations.
 * Provides methods for configuring SOAP endpoints, headers, and QName computation.
 *
 * @author sfloess
 * @since 1.0
 */
public final class SoapUtil {

    /**
     * Gets a new SOAP factory instance.
     * 
     * @return a new SOAPFactory instance
     * @throws SoapException if factory cannot be instantiated
     * @since 1.0
     */
    public static SOAPFactory getSoapFactory() {
```

### SoapRecord (added recently)
```java
/**
 * Record type to hold a SOAP service and the port class type.
 *
 * @param <T> the port type
 * @param service the SOAP service instance
 * @param portType the port class type
 * @author sfloess
 * @since 1.30
 */
public record SoapRecord<T>(Service service, Class<T> portType) {
```

### StringUtil.requireNonBlank (check Git to confirm)
```java
/**
 * Validates that a string is not null, empty, or whitespace-only.
 *
 * @param string the string to validate
 * @param message the error message to use if validation fails
 * @return the validated string
 * @throws IllegalArgumentException if the string is blank
 * @since 1.28
 */
public static String requireNonBlank(final String string, final String message) {
```

## Benefits

1. **Version clarity** - Users know when APIs were added
2. **Upgrade planning** - Can see new features by version
3. **Professional docs** - Industry standard practice
4. **IDE integration** - Better code completion info
5. **Deprecation context** - Know how long API existed

## Automated Script

To add `@since 1.0` to all existing APIs:

```bash
#!/bin/bash
# Add @since to all public classes without it

for file in $(find src/main/java -name "*.java"); do
    # Check if public class/interface/enum/record
    if grep -q "^public.*class\|^public.*interface\|^public.*enum\|^public.*record" "$file"; then
        # Check if @since already present
        if ! grep -q "@since" "$file"; then
            echo "Adding @since to $file"
            # Add @since before class declaration
            # (This is simplified - real script needs better sed)
        fi
    fi
done
```

**Note:** Manual review recommended over automated changes.

## Related Issues

Would complement:
- Issue #128 - Deprecation metadata (shows when deprecated)
- Issue #135 - CONTRIBUTING.md (document the standard)

This issue adds: **When was it added?**

Missing @since JavaDoc tags - no version tracking for API additions #142

Description

Description

Current State

❌ No @SInCE Tags Anywhere

❌ No @Version Tags

✅ Version in pom.xml

Why @SInCE Tags Matter

1. API Version Tracking

2. Deprecation Context

3. Migration Planning

4. Documentation Quality

5. IDE Integration

Impact

Recommended Fix

1. Add @SInCE to All Public APIs

2. Determine When Each API Was Added

3. Update CONTRIBUTING.md

Methods

Deprecations

5. Update maven-javadoc-plugin

Migration Strategy

Phase 1: Existing Code (v1.32)

Phase 2: New Code (v1.32+)

Phase 3: Enforcement (v2.0)

Example Updates

SoapUtil (exists since project start)

SoapRecord (added recently)

StringUtil.requireNonBlank (check Git to confirm)

Benefits

Automated Script

Related Issues

Metadata

Metadata

Assignees

Labels

Type

Fields

Projects

Milestone

Relationships

Development

Issue actions