Updated docs for FileCache.

modules/web/doc_classes/FileCache.xml

@@ -1,15 +1,13 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="FileCache" inherits="Reference" version="4.3">
 	<brief_description>
-		The FileCache class provide functionality for file and directory caching for the web module.
+		The FileCache class provide functionality for file caching and name and path sanitization for the web module.
 	</brief_description>
 	<description>
-		The FileCache class provide functionality for file and directory caching for the web module.
+		The FileCache class provide functionality for file caching and name and path sanitization for the web module.
-		It can evaluate a folder, and save all file paths into memory.
+		It helps with avoiding directory traversal attacks, as relative paths are not going to be expanded by accident.
-		Using this functionality can increase performance in certain scenarios, as the application does not have to use a syscall to evaluate whether a file exists or not, and also helps with avoiding directory traversal attacks, as relative paths are not going to be expanded by accident.
 		(A directory traversal attach would be if an application receives this get request: [code]server.net/../../../etc/passwd[/code], and it would result in success, if the app then returns the contents of the "passwd" file, which is outside of the root folder of the server.)
-		[FileCache] has a drawback for now, as it doesn't yet watch for changes in the folder, so if files change it needs to be manually refreshed.
+		It can save contents of files or pages into memory if needed using the [code]set_cached_body()[/code] helper method.
-		It can also save contents of files into memory if needed using the [code]set_cached_body()[/code] helper method.
 	</description>
 	<tutorials>
 	</tutorials>
@@ -17,23 +15,27 @@
 		<method name="clear">
 			<return type="void" />
 			<description>
+				Clear all internal caches.
 			</description>
 		</method>
 		<method name="get_cached_body">
 			<return type="String" />
 			<argument index="0" name="path" type="String" />
 			<description>
+				Get a previously stored page's or file's body.
 			</description>
 		</method>
 		<method name="get_wwwroot_abs">
 			<return type="String" />
 			<description>
+				Return the set [member wwwroot]'s absolute path.
 			</description>
 		</method>
 		<method name="has_cached_body">
 			<return type="bool" />
 			<argument index="0" name="path" type="String" />
 			<description>
+				Check whether a page's or file's body is available.
 			</description>
 		</method>
 		<method name="set_cached_body">
@@ -41,25 +43,43 @@
 			<argument index="0" name="path" type="String" />
 			<argument index="1" name="body" type="String" />
 			<description>
+				Store a page's or file's body.
 			</description>
 		</method>
 		<method name="wwwroot_get_file_abspath">
 			<return type="String" />
 			<argument index="0" name="file_path" type="String" />
 			<description>
+				Returns the absolute path to a file if it exists in the given [member wwwroot]. If it doesn't exists returns an empty [String].
+				Guards against directory traversal.
+				Note: file path should be the url you want to access the file with, including lead slash. e.g. http://127.0.0.1/a/b/d.jpg -> /a/b/d.jpg
+			</description>
+		</method>
+		<method name="wwwroot_get_simplified_abs_path">
+			<return type="String" />
+			<argument index="0" name="file_path" type="String" />
+			<description>
+				Returns the absolute path to a file in the given [member wwwroot]. Does not checks if the file exists or not. Returns an empty [String] on error.
+				Guards against directory traversal.
+				Note: file path should be the url you want to access the file with, including lead slash. e.g. http://127.0.0.1/a/b/d.jpg -> /a/b/d.jpg
 			</description>
 		</method>
 		<method name="wwwroot_has_file">
 			<return type="bool" />
 			<argument index="0" name="file_path" type="String" />
 			<description>
+				Check whether a file exists in the given [member wwwroot].
+				Guards against directory traversal.
+				Note: file path should be the url you want to access the file with, including lead slash. e.g. http://127.0.0.1/a/b/d.jpg -> /a/b/d.jpg
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="cache_invalidation_time" type="int" setter="set_cache_invalidation_time" getter="get_cache_invalidation_time" default="0">
+			How long a page's or file's body should be stored.
 		</member>
 		<member name="wwwroot" type="String" setter="set_wwwroot" getter="get_wwwroot" default="&quot;&quot;">
+			Set a www root directory for this [FileCache]. It can be both relative and absolute.
 		</member>
 	</members>
 	<constants>