docs: add @permission kdoc to stdlib functions

Author: iamgio

quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlib/Bibliography.kt

@@ -15,6 +15,7 @@ import com.quarkdown.core.function.reflect.annotation.LikelyNamed
 import com.quarkdown.core.function.reflect.annotation.Name
 import com.quarkdown.core.function.value.NodeValue
 import com.quarkdown.core.function.value.wrappedAsValue
+import com.quarkdown.core.permissions.Permission
 
 /**
  * `Bibliography` stdlib module exporter.
@@ -64,6 +65,8 @@ private const val DEFAULT_CSL_STYLE = "ieee"
  * @see cite to cite bibliography entries
  * @throws java.io.IOException if the bibliography file cannot be read or parsed
  * @throws IllegalArgumentException if the specified style does not exist or is invalid
+ * @permission [Permission.ProjectRead] to read bibliography files located in the project directory
+ * @permission [Permission.GlobalRead] to read bibliography files located outside the project directory
  * @wiki Bibliography
  */
 fun bibliography(

quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlib/Data.kt

@@ -23,6 +23,7 @@ import com.quarkdown.core.function.value.data.Range
 import com.quarkdown.core.function.value.data.subList
 import com.quarkdown.core.function.value.factory.ValueFactory
 import com.quarkdown.core.function.value.wrappedAsValue
+import com.quarkdown.core.permissions.Permission
 import com.quarkdown.core.permissions.requireReadPermission
 import com.quarkdown.core.util.normalizeLineSeparators
 import com.quarkdown.stdlib.internal.AlphanumericComparator
@@ -71,6 +72,8 @@ internal fun file(
  * @param lineRange range of lines to extract from the file.
  *                  If not specified or infinite, the whole file is read
  * @return a string value of the text extracted from the file
+ * @permission [Permission.ProjectRead] to read files located in the project directory
+ * @permission [Permission.GlobalRead] to read files located outside the project directory
  * @throws IllegalArgumentException if [lineRange] is out of bounds
  * @wiki File data
  */
@@ -196,6 +199,8 @@ enum class FileSorting(
  * @param order order to sort the files in
  * @return an unordered collection of string values, each representing a file located in the directory, with extension
  * @throws IllegalArgumentException if the directory does not exist or if the path is not a directory
+ * @permission [Permission.ProjectRead] to list files located in the project directory
+ * @permission [Permission.GlobalRead] to list files located outside the project directory
  * @see fileName to exclude the extension from file names
  * @wiki File data
  */
@@ -239,6 +244,8 @@ fun listFiles(
  * @param includeExtension whether to include the file extension in the name
  * @return the name of the file located in [path]
  * @throws IllegalArgumentException if the file does not exist
+ * @permission [Permission.ProjectRead] to access files located in the project directory
+ * @permission [Permission.GlobalRead] to access files located outside the project directory
  * @wiki File data
  */
 @Name("filename")
@@ -273,6 +280,8 @@ enum class CsvParsingMode(
  * @param caption optional caption of the table. If set, the table will be numbered according to the current [numbering] format
  * @param referenceId optional ID for cross-referencing via [reference]
  * @return a table whose content is loaded from the file located in [path]
+ * @permission [Permission.ProjectRead] to read CSV files located in the project directory
+ * @permission [Permission.GlobalRead] to read CSV files located outside the project directory
  * @wiki File data
  */
 fun csv(

quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlib/Injection.kt

@@ -42,6 +42,7 @@ val Injection: QuarkdownModule =
  *
  * @param content raw HTML content to inject
  * @return a new [Html] node
+ * @permission [Permission.NativeContent] to inject native HTML content
  * @throws com.quarkdown.core.permissions.MissingPermissionException if [Permission.NativeContent] is not granted
  * @wiki HTML
  */
@@ -73,6 +74,7 @@ fun html(
  *
  * @param content raw CSS content to inject
  * @return a new [Html] node representing the style element
+ * @permission [Permission.NativeContent] to inject native CSS content
  * @throws com.quarkdown.core.permissions.MissingPermissionException if [Permission.NativeContent] is not granted
  * @see [cssProperties] for a more structured way to override CSS properties.
  * @wiki CSS
@@ -107,8 +109,9 @@ private const val CSS_PROPERTY_PREFIX = "--qd-"
  * without any additional processing or escaping, as long as the rendering target supports HTML.
  *
  * @param properties a dictionary of CSS property names and their values
- * @throws com.quarkdown.core.permissions.MissingPermissionException if [Permission.NativeContent] is not granted
  * @return a new [Html] node representing the style element
+ * @permission [Permission.NativeContent] to inject native CSS properties
+ * @throws com.quarkdown.core.permissions.MissingPermissionException if [Permission.NativeContent] is not granted
  * @wiki CSS
  */
 @Name("cssproperties")