feat: fix javadoc (casbin#432)

Author: sukidayou

pom.xml

@@ -85,7 +85,11 @@
                     <source>11</source>
                     <detectJavaApiLink>false</detectJavaApiLink>
                     <!-- Turn off Java 8 strict Javadoc checking -->
-                    <additionalparam>-Xdoclint:none</additionalparam>
+<!--                    <additionalparam>-Xdoclint:none</additionalparam>-->
+                    <doclint>none</doclint>
+                    <sourceFileIncludes>
+                        <sourceFileInclude>**/*.java</sourceFileInclude>
+                    </sourceFileIncludes>
                     <tags>
                         <tag>
                             <name>notnull</name>

src/main/java/org/casbin/jcasbin/main/CoreEnforcer.java

@@ -486,7 +486,7 @@ public void enableAutoBuildRoleLinks(boolean autoBuildRoleLinks) {
     /**
      * EnableAcceptJsonRequest controls whether to accept json as a request parameter
      *
-     * @param acceptJsonRequest
+     * @param acceptJsonRequest a boolean that indicates whether JSON requests are accepted.
      */
     public void enableAcceptJsonRequest(boolean acceptJsonRequest) {
         this.acceptJsonRequest = acceptJsonRequest;
@@ -782,6 +782,11 @@ public EnforceResult enforceExWithMatcher(String matcher, Object... rvals) {
 
     /**
      * addNamedMatchingFunc add MatchingFunc by ptype RoleManager
+     *
+     * @param ptype the type of the role manager.
+     * @param name  the name of the matching function to be added.
+     * @param fn    the matching function.
+     * @return whether the matching function was successfully added.
      */
     public boolean addNamedMatchingFunc(String ptype, String name, BiPredicate<String, String> fn) {
         if (rmMap.containsKey(ptype)) {
@@ -798,6 +803,11 @@ public boolean addNamedMatchingFunc(String ptype, String name, BiPredicate<Strin
 
     /**
      * addNamedMatchingFunc add MatchingFunc by ptype RoleManager
+     *
+     * @param ptype the type of the role manager.
+     * @param name  the name of the matching function to be added.
+     * @param fn    the domain matching function.
+     * @return whether the matching function was successfully added.
      */
     public boolean addNamedDomainMatchingFunc(String ptype, String name, BiPredicate<String, String> fn) {
         if (rmMap.containsKey(ptype)) {
@@ -813,8 +823,14 @@ public boolean addNamedDomainMatchingFunc(String ptype, String name, BiPredicate
     }
 
     /**
-     * addNamedLinkConditionFunc Add condition function fn for Link userName->roleName,
+     * addNamedLinkConditionFunc Add condition function fn for Link userName-&gt;roleName,
      * when fn returns true, Link is valid, otherwise invalid
+     *
+     * @param ptype the type of the role manager.
+     * @param user  the username for which the link condition is being added.
+     * @param role  the role associated with the user for which the condition is evaluated.
+     * @param fn    a function that takes an array of parameters (e.g., [user, role]) and returns a Boolean indicating the validity of the link.
+     * @return whether the Link is valid.
      */
     public boolean addNamedLinkConditionFunc(String ptype, String user, String role, Function<String[], Boolean> fn){
         if (condRmMap.containsKey(ptype)){
@@ -826,8 +842,15 @@ public boolean addNamedLinkConditionFunc(String ptype, String user, String role,
     }
 
     /**
-     * addNamedDomainLinkConditionFunc Add condition function fn for Link userName-> {roleName, domain},
+     * addNamedDomainLinkConditionFunc Add condition function fn for Link userName-&gt; {roleName, domain},
      * when fn returns true, Link is valid, otherwise invalid
+     *
+     * @param ptype  the type of the conditional role manager.
+     * @param user   the username for which the link condition is being added.
+     * @param role   the role associated with the user for which the condition is evaluated.
+     * @param domain the domain associated with the role.
+     * @param fn     a function that takes an array of parameters (e.g., [user, role, domain]) and returns a Boolean indicating the validity of the link.
+     * @return whether the Link is valid.
      */
     public boolean addNamedDomainLinkConditionFunc(String ptype, String user, String role, String domain, Function<String[], Boolean> fn) {
         if (condRmMap.containsKey(ptype)){
@@ -839,7 +862,13 @@ public boolean addNamedDomainLinkConditionFunc(String ptype, String user, String
     }
 
     /**
-     * setNamedLinkConditionFuncParams Sets the parameters of the condition function fn for Link userName->roleName
+     * setNamedLinkConditionFuncParams Sets the parameters of the condition function fn for Link userName-&gt;roleName
+     *
+     * @param ptype  the type of the conditional role manager.
+     * @param user   the username for which the link condition parameters are being set.
+     * @param role   the role associated with the user for which the parameters are being configured.
+     * @param params an array of parameters to be passed to the condition function.
+     * @return whether the Link is valid.
      */
     public boolean setNamedLinkConditionFuncParams(String ptype, String user, String role, String... params){
         if (condRmMap.containsKey(ptype)){
@@ -852,7 +881,14 @@ public boolean setNamedLinkConditionFuncParams(String ptype, String user, String
 
     /**
      * setNamedDomainLinkConditionFuncParams Sets the parameters of the condition function fn
-     * for Link userName->{roleName, domain}
+     * for Link userName-&gt;{roleName, domain}
+     *
+     * @param ptype  the type of the conditional role manager.
+     * @param user   the username for which the link condition parameters are being set.
+     * @param role   the role associated with the user for which the parameters are being configured.
+     * @param domain the domain associated with the role and user.
+     * @param params an array of parameters to be passed to the condition function, allowing customization of the condition logic.
+     * @return whether the parameters were successfully set.
      */
     public boolean setNamedDomainLinkConditionFuncParams(String ptype, String user, String role, String domain, String... params){
         if (condRmMap.containsKey(ptype)){
@@ -863,6 +899,14 @@ public boolean setNamedDomainLinkConditionFuncParams(String ptype, String user,
         return false;
     }
 
+    /***
+     * getRTokens Retrieves request tokens and populates them into the provided parameters map.
+     *
+     * @param parameters a map to store the request tokens and their corresponding values.
+     * @param rType      the type of the request for which tokens are being retrieved, used to access the appropriate model.
+     * @param rvals      the request needs to be mediated, usually an array
+     *                   of strings, can be class instances if ABAC is used.
+     */
     private void getRTokens(Map<String, Object> parameters, String rType, Object... rvals) {
         String[] requestTokens = model.model.get("r").get(rType).tokens;
         if(requestTokens.length != rvals.length) {
@@ -874,6 +918,14 @@ private void getRTokens(Map<String, Object> parameters, String rType, Object...
         }
     }
 
+    /***
+     * getPTokens Retrieves policy tokens and populates them into the provided parameters map.
+     *
+     * @param parameters a map to store the policy tokens and their corresponding values.
+     * @param pType the type of the policy for which tokens are being retrieved, used for context.
+     * @param pvals a list of values corresponding to the policy tokens.
+     * @param pTokens an array of tokens associated with the policy.
+     */
     private void getPTokens(Map<String, Object> parameters, String pType, List<String> pvals, String[] pTokens) {
         if (pTokens.length != pvals.size()) {
             throw new CasbinMatcherException("invalid policy size: expected " + pTokens.length +

src/main/java/org/casbin/jcasbin/main/DistributedEnforcer.java

@@ -101,7 +101,7 @@ public DistributedEnforcer(String modelPath, String policyFile, boolean enableLo
      * AddPolicySelf provides a method for dispatcher to add authorization rules to the current policy.
      * The function returns the rules affected and error.
      *
-     * @param shouldPersist
+     * @param shouldPersist whether the changes should be persisted.
      * @param sec     the section, "p" or "g".
      * @param ptype   the policy type, "p", "p2", .. or "g", "g2", ..
      * @param rules   the rules.
@@ -146,7 +146,7 @@ public List<List<String>> addPolicySelf(BooleanSupplier shouldPersist, String se
      * RemovePolicySelf provides a method for dispatcher to remove policies from current policy.
      * The function returns the rules affected and error.
      *
-     * @param shouldPersist
+     * @param shouldPersist whether the changes should be persisted.
      * @param sec     the section, "p" or "g".
      * @param ptype   the policy type, "p", "p2", .. or "g", "g2", ..
      * @param rules   the rules.
@@ -184,7 +184,7 @@ public List<List<String>> removePolicySelf(BooleanSupplier shouldPersist, String
      * field filters can be specified.
      * The function returns the rules affected and error.
      *
-     * @param shouldPersist
+     * @param shouldPersist whether the changes should be persisted.
      * @param sec     the section, "p" or "g".
      * @param ptype   the policy type, "p", "p2", .. or "g", "g2", ..
      * @param fieldIndex the policy rule's start index to be matched.
@@ -220,7 +220,7 @@ public List<List<String>> removeFilteredPolicySelf(BooleanSupplier shouldPersist
     /**
      * ClearPolicySelf provides a method for dispatcher to clear all rules from the current policy.
      *
-     * @param shouldPersist
+     * @param shouldPersist whether the changes should be persisted.
      */
     public void clearPolicySelf(BooleanSupplier shouldPersist) {
         if (shouldPersist.getAsBoolean()) {
@@ -239,7 +239,7 @@ public void clearPolicySelf(BooleanSupplier shouldPersist) {
     /**
      * UpdatePolicySelf provides a method for dispatcher to update an authorization rule from the current policy.
      *
-     * @param shouldPersist
+     * @param shouldPersist whether the changes should be persisted.
      * @param sec     the section, "p" or "g".
      * @param ptype   the policy type, "p", "p2", .. or "g", "g2", ..
      * @param oldRule the old rule.

src/main/java/org/casbin/jcasbin/model/Model.java

@@ -165,6 +165,8 @@ private void loadSections(Config cfg) {
 
     /**
      * SetLogger sets the model's logger.
+     *
+     * @param logger the logger to be set for the model.
      */
     public void setLogger(Logger logger) {
         for (Map<String, Assertion> astMap : model.values()) {
@@ -177,6 +179,8 @@ public void setLogger(Logger logger) {
 
     /**
      * NewModel creates an empty model.
+     *
+     * @return a new instance of the Model.
      */
     public static Model newModel() {
         Model model = new Model();
@@ -188,6 +192,7 @@ public static Model newModel() {
      * NewModelFromString creates a model from a string which contains model text.
      *
      * @param path the path of the model file.
+     * @return the model loaded from file.
      */
     public static Model newModelFromFile(String path) {
         Model model = new Model();
@@ -199,6 +204,7 @@ public static Model newModelFromFile(String path) {
      * NewModelFromString creates a model from a string which contains model text.
      *
      * @param text the path of the file.
+     * @return the model loaded from text.
      */
     public static Model newModelFromString(String text) {
         Model model = new Model();
@@ -250,6 +256,9 @@ public void loadModelFromConfig(Config cfg) {
 
     /**
      * hasSection checks if the section exists in the model.
+     *
+     * @param sec the section name to check, such as "p" or "g".
+     * @return  whether the section exists in the model.
      */
     public boolean hasSection(String sec) {
         Map<String, Assertion> section = model.get(sec);

src/main/java/org/casbin/jcasbin/model/Policy.java

@@ -392,6 +392,12 @@ public boolean hasPolicies(String sec, String ptype, List<List<String>> rules) {
 
     /**
      * buildIncrementalConditionalRoleLinks provides incremental build the role inheritance relations.
+     *
+     * @param condRmMap a map of conditional role managers used for role link management.
+     * @param op        the operation to perform, such as adding or removing role links.
+     * @param sec       the section of the policy, typically "g" for role inheritance.
+     * @param ptype     the policy type, which specifies the kind of roles being managed.
+     * @param rules     the rules that define the role links to be built.
      */
     public void buildIncrementalConditionalRoleLinks(Map<String, ConditionalRoleManager> condRmMap, Model.PolicyOperations op, String sec, String ptype, List<List<String>> rules){
         if ("g".equals(sec) && condRmMap.containsKey(ptype)) {
@@ -401,6 +407,8 @@ public void buildIncrementalConditionalRoleLinks(Map<String, ConditionalRoleMana
 
     /**
      * buildConditionalRoleLinks initializes the roles in RBAC.
+     *
+     * @param condRmMap a map of conditional role managers that manage the role links and their conditions.
      */
     public void buildConditionalRoleLinks(Map<String, ConditionalRoleManager> condRmMap){
         printPolicy();

src/main/java/org/casbin/jcasbin/persist/Dispatcher.java

@@ -22,27 +22,30 @@
  */
 public interface Dispatcher {
     /**
-     * // AddPolicies adds policies rule to all instance.
-     * @param sec
-     * @param ptype
-     * @param rules
+     * AddPolicies adds policies rule to all instance.
+     *
+     * @param sec   the section to which the policies belong, e.g., "p" or "g".
+     * @param ptype the policy type, such as "p" for permissions or "g" for roles.
+     * @param rules the list of policy rules to be added, where each rule is represented as a list of strings.
      */
     void addPolicies(String sec, String ptype, List<List<String>> rules);
 
     /**
      * RemovePolicies removes policies rule from all instance.
-     * @param sec
-     * @param ptype
-     * @param rules
+     *
+     * @param sec   the section from which to remove policies, e.g., "p" or "g".
+     * @param ptype the policy type to remove, such as "p" or "g".
+     * @param rules the list of policy rules to be removed, where each rule is represented as a list of strings.
      */
     void removePolicies(String sec, String ptype, List<List<String>> rules);
 
     /**
      * RemoveFilteredPolicy removes policy rules that match the filter from all instance.
-     * @param sec
-     * @param ptype
-     * @param fieldIndex
-     * @param fieldValues
+     *
+     * @param sec         the section from which to remove policies, e.g., "p" or "g".
+     * @param ptype       the policy type to filter, such as "p" or "g".
+     * @param fieldIndex  the index of the field to filter on.
+     * @param fieldValues the values to filter by for the specified field index.
      */
     void removeFilteredPolicy(String sec, String ptype, int fieldIndex, String... fieldValues);
 
@@ -53,10 +56,11 @@ public interface Dispatcher {
 
     /**
      * UpdatePolicy updates policy rule from all instance.
-     * @param sec
-     * @param ptype
-     * @param oldRule
-     * @param newRule
+     *
+     * @param sec     the section containing the policy, e.g., "p" or "g".
+     * @param ptype   the policy type to update, such as "p" or "g".
+     * @param oldRule the existing policy rule to be updated, represented as a list of strings.
+     * @param newRule the new policy rule that will replace the old one, represented as a list of strings.
      */
     void updatePolicy(String sec, String ptype, List<String> oldRule, List<String> newRule);
 }