/*
 * @author Ranides Atterwim <ranides@gmail.com>
 * @copyright Ranides Atterwim
 * @license WTFPL
 * @url http://ranides.net/projects/assira
 */
package net.ranides.assira.annotations;

import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.*;

/**
 * Adnotacje dla PMD. Pozwalają wskazać przeznaczenie / charakterystykę danego
 * fragmentu kodu, a PMD na tej podstawie włączy lub wyłączy niektóre reguły.
 *
 * <p>reguły zwracające uwagę na adnotacje jeszcze nie zaimplementowane</p>
 * @author ranides
 */
@SuppressWarnings("PMD.PackageClass")
public final class PMD {

    private PMD() {
        // utility class
    }

    /**
     * Klasa testowa, może mieć dużo danych pomieszanych z kodem
     * <p><b>Suppress:</b></p>
     * <ul>
     *      <li>PMD.AvoidDuplicateLiterals</li>
     * </ul>
     * 
     * @todo (migration) implement in assira.rules
     */
    @Retention(SOURCE)
    @Target({TYPE,METHOD})
    public @interface UnitTest {
    }


    /**
     * Klasa intensywnie latająca po tablicach, których właścicielem jest ktoś inny
     * <p><b>Suppress:</b></p>
     * <ul>
     *      <li>PMD.ArrayIsStoredDirectly</li>
     *      <li>PMD.MethodReturnsInternalArray</li>
     *      <li>PMD.AvoidArrayLoops</li>
     *      <li>PMD.SingularField</li>
     * </ul>
     * 
     * @todo (migration) implement in assira.rules
     */
    @Retention(SOURCE)
    @Target({TYPE,METHOD})
    public @interface ArrayWrapper {
    }

    /**
     * Klasa definijąca umyślnie metody, których nazwy są w stylu innym niż java
     * <p><b>Suppress:</b></p>
     * <ul>
     *      <li>PMD.MethodNameRules</li>
     * </ul>
     * 
     * @todo (migration) implement in assira.rules
     */
    @Retention(SOURCE)
    @Target({TYPE,METHOD})
    public @interface API {

        /**
         * Konwencja nazw użyta zamiast reguł zalecanych przez Sun'a
         * @return default "C"
         */
        String style() default "C";

    }


    /**
     * Formatka SWINGa, kod generowany dla swinga łamie serię reguł PMD z definicji
     * <p><b>Suppress:</b></p>
     * <ul>
     *      <li>PMD.TooManyFields</li>
     *      <li>PMD.TooManyDifferentMethods</li>
     * </ul>
     * 
     * @todo (migration) implement in assira.rules
     */
    @Retention(SOURCE)
    @Target({TYPE,METHOD})
    public @interface SwingForm {
    }


    /**
     * Utility class, posiada tylko metody statyczne, nie można tworzyć jej instancji
     * <p><b>Suppress:</b></p>
     * <ul>
     *      <li>PMD.UseSingleton</li>
     * </ul>
     */
    @Retention(SOURCE)
    @Target({TYPE})
    public @interface StaticHelper {
    }
    
    /**
     * Metoda pseudo-matematyczna, może pobierać argumenty o krótkich nazwach: a, b, c, d ...
     * <p><b>Suppress:</b></p>
     * <ul>
     *      <li>PMD.ShortVar</li>
     * </ul>
     */
    @Retention(SOURCE)
    @Target({TYPE,METHOD})
    public @interface Math {
    }

}
