[Pkg-privacy-commits] [libgsecuredelete] 74/168: Fix the documentation to follow ValaDoc format
Ulrike Uhlig
u-guest at moszumanska.debian.org
Thu Jul 7 20:06:41 UTC 2016
This is an automated email from the git hooks/post-receive script.
u-guest pushed a commit to branch master
in repository libgsecuredelete.
commit 80cac0a3aa019e4f200a4b8220c378b1100d74c9
Author: Colomban Wendling <ban at herbesfolles.org>
Date: Fri Apr 29 19:36:34 2011 +0200
Fix the documentation to follow ValaDoc format
Use ValaDoc syntax for documentation comments, allowing future
generation of the documentation.
Also clean the documentation a bit in some places.
---
gsecuredelete/async-operation.vala | 166 +++++++++++++++---------------
gsecuredelete/delete-operation.vala | 30 +++---
gsecuredelete/fill-operation.vala | 51 ++++-----
gsecuredelete/mem-operation.vala | 5 +-
gsecuredelete/securedelete-operation.vala | 40 ++++---
gsecuredelete/swap-operation.vala | 30 +++---
gsecuredelete/utils.vala | 68 ++++++------
gsecuredelete/zeroable-operation.vala | 9 +-
8 files changed, 204 insertions(+), 195 deletions(-)
diff --git a/gsecuredelete/async-operation.vala b/gsecuredelete/async-operation.vala
index 266a1a1..7357419 100644
--- a/gsecuredelete/async-operation.vala
+++ b/gsecuredelete/async-operation.vala
@@ -21,18 +21,24 @@ using GLib;
namespace Gsd
{
- /** AsyncOperationError:
- *
+ /**
* Error domain for the AsyncOperation class.
- * @ARGS_ERROR: An error occurred during the build of the command's arguments.
- * @CHILD_FAILED: The subprocess crashed or terminated with an error.
- * @SUBCLASS_ERROR: Other error from a subclass of AsyncOperation. This is
- * used as a workaround for the lack of error subclassing,
- * disallowing to manage "generic" errors cleanly.
*/
public errordomain AsyncOperationError {
+ /**
+ * An error occurred during the build of the command's arguments.
+ */
ARGS_ERROR,
+ /**
+ * The subprocess crashed or terminated with an error.
+ */
CHILD_FAILED,
+ /**
+ * Other error from a subclass of AsyncOperation.
+ *
+ * This is used as a workaround for the lack of error subclassing,
+ * disallowing to manage "generic" errors cleanly.
+ */
SUBCLASS_ERROR /* workaround the miss of error subclassing */
}
@@ -40,10 +46,10 @@ namespace Gsd
* TODO:
* * Be able to launch the operation as root/another user.
*/
- /** AsyncOperation:
- *
+ /**
* An asynchronous process spawner, with support for progression and success
* report.
+ *
* This is a base class designed to be subclassed by actual spawners, with
* as less efforts as possible.
*
@@ -54,37 +60,17 @@ namespace Gsd
* set it since it must be set before calling run() or run_sync() - or getting
* it).
* This said, you may want to override get_max_progress() and get_progress()
- * to add actual progress support; build_environ() to provide a specific
+ * to add actual progress support; and build_environ() to provide a specific
* environment to your command.
*
- * <warning>
- * As it use a timeout function to watch the child, you need a GLib's
- * MainLoop for the watching process to work for the asynchronous method.
- *
- * Yes, a thread might be a good thing, but have some limitations too:
- * <list>
- * <listentry>
- * Still needs a timeout somewhere not to overload the machine;
- * This can perhaps be thrown away by waiting for the process or one
- * of its outputs to be "ready" for something.
- * </listentry>
- * <listentry>
- * Needs lot of care both for the implementation and even more for the
- * caller in most cases;
- * </listentry>
- * <listentry>
- * Doesn't do magic: you still need to wait for the thread to terminate
- * in a certain manner, or let the thread terminate together with the
- * application.
- * </listentry>
- * </list>
- * If you find a perfect implementation going away these limitations, please
- * tell me and I'll be happy to try to implement it or to review your patch.
- * </warning>
+ * =Important note=
*
- * <example>
- * <title>Simple usage of an hypothetical subclass FooOperation</title>
- * <programlisting>
+ * As this class uses a timeout function to watch the child, you need a GLib
+ * MainLoop for the watching process to work for the asynchronous method.
+ *
+ * =Simple usage of an hypothetical FooOperation subclass=
+ *
+ * {{{
* var foo = new FooOperation();
*
* // Connect the finish callback
@@ -103,49 +89,60 @@ namespace Gsd
*
* var loop = GLib.MainLoop (null, false);
* loop.run ();
- * </programlisting>
- * </example>
- *
- * @n_passes: the maximum number of progress steps.
- * @passes: the current progress step
- * @pid: the subprocess PID
- * @fd_in: the subprocess' standard input
- * @fd_out: the subprocess' standard output
- * @fd_err: the subprocess' error output
+ * }}}
*/
public abstract class AsyncOperation : Object
{
/* fields for async operation */
+ /**
+ * The maximum number of progress steps.
+ */
protected uint n_passes;
+ /**
+ * the current progress step
+ */
protected uint passes;
+ /**
+ * the subprocess PID
+ */
protected Pid pid;
+ /**
+ * the subprocess' standard input
+ */
protected int fd_in;
+ /**
+ * the subprocess' standard output
+ */
protected int fd_out;
+ /**
+ * the subprocess' error output
+ */
protected int fd_err;
private bool _busy = false;
private string _path = null;
private string _path_default = null;
/* signals */
- /** AsyncOperation::finished:
- * @success: whether the operation succeed.
- * @message: if the operation failed, contains the error message.
- *
+ /**
* This signal is emitted when the operation just terminated.
+ *
+ * @param success whether the operation succeed.
+ * @param message if the operation failed, contains the error message.
*/
public signal void finished (bool success,
string? message);
- /** AsyncOperation::progress:
- * @fraction: the current progress, from 0.0 to 1.0.
- *
+ /**
* This signal is emitted when the progress status of the operation changes.
+ *
+ * @param fraction the current progress, from 0.0 to 1.0.
*/
public signal void progress (double fraction);
/* properties */
- /** path:
+ /**
* The path to the command to spawn.
- * Setting it to %null resets it to its default value.
+ *
+ * Setting it to null resets it to its default value.
*/
public string path {
get {
@@ -168,10 +165,11 @@ namespace Gsd
}
}
}
- /** AsyncOperation: busy:
- * Whether the operation object is busy. A busy operation cannot be reused
- * until it gets ready again. An operation is busy when it is currently
- * doing a job.
+ /**
+ * Whether the operation object is busy.
+ *
+ * A busy operation cannot be reused until it gets ready again.
+ * An operation is busy when it is currently doing a job.
*/
public bool busy {
public get {
@@ -319,10 +317,10 @@ namespace Gsd
return ! finished;
}
- /** cancel:
+ /**
* Tries to cancel the operation.
*
- * Returns: %true if successfully canceled, %false otherwise.
+ * @return true if successfully canceled, false otherwise.
*/
public bool cancel ()
requires (this.busy)
@@ -337,18 +335,18 @@ namespace Gsd
return ! (kill_status < 0);
}
- /** run:
- * @working_directory: the working directory of the child process, or null
- * to use the parent's one.
- * @spawn_flags: %SpawnFlags. You may only use the SEARCH_PATH and
- * CHILD_INHERITS_STDIN flags, others may conflict.
- * @watch_interval: time (in milliseconds) between two check for subprocess'
- * status. A too short value may use too much CPU and a too
- * big may be less responsive.
- *
+ /**
* Launches an operation asynchronously.
*
- * Returns: whether asynchronous operation was successfully started.
+ * @param working_directory the working directory of the child process, or
+ * null to use the parent's one.
+ * @param spawn_flags SpawnFlags. You may only use the SEARCH_PATH and
+ * CHILD_INHERITS_STDIN flags, others may conflict.
+ * @param watch_interval time (in milliseconds) between two check for
+ * subprocess' status. A too short value may use too much CPU and a too
+ * big may be less responsive.
+ *
+ * @return whether asynchronous operation was successfully started.
*/
public bool run (string? working_directory = null,
SpawnFlags spawn_flags = 0,
@@ -391,21 +389,21 @@ namespace Gsd
return success;
}
- /** run_sync:
- * @working_directory: the working directory of the child process, or null
- * to use the parent's one.
- * spawn_flags: %SpawnFlags. You may only use the SEARCH_PATH and
- * CHILD_INHERITS_STDIN flags, others may conflict.
- * @standard_output: return location for the subprocess' standard output,
- * or null to ignore it.
- *
+ /**
* Launches an operation synchronously.
*
- * Returns: %true if all worked properly, and %false if something failed.
- * An error is thrown if something fails. It can be the subprocess
- * spawning (SpawnError) or the child that failed
- * (AsyncOperationError.CHILD_FAILED) or the generation of
- * arguments that failed (AsyncOperationError.ARGS_ERROR).
+ * @param working_directory the working directory of the child process, or
+ * null to use the parent's one.
+ * @param spawn_flags SpawnFlags. You may only use the SEARCH_PATH and
+ * CHILD_INHERITS_STDIN flags, others may conflict.
+ * @param standard_output return location for the subprocess' standard
+ * output, or null to ignore it.
+ *
+ * @return true if all worked properly, and false if something failed.
+ * An error is thrown if something fails. It can be the subprocess
+ * spawning (SpawnError) or the child that failed
+ * (AsyncOperationError.CHILD_FAILED) or the generation of
+ * arguments that failed (AsyncOperationError.ARGS_ERROR).
*/
public bool run_sync (string? working_directory = null,
SpawnFlags spawn_flags = 0,
diff --git a/gsecuredelete/delete-operation.vala b/gsecuredelete/delete-operation.vala
index d3db047..21c8c68 100644
--- a/gsecuredelete/delete-operation.vala
+++ b/gsecuredelete/delete-operation.vala
@@ -21,9 +21,8 @@ using GLib;
namespace Gsd
{
- /** DeleteOperation:
- *
- * Wrapper for `srm`.
+ /**
+ * Wrapper for //srm//.
*/
public class DeleteOperation : ZeroableOperation
{
@@ -31,7 +30,7 @@ namespace Gsd
private uint n_files = 0;
/* properties */
- /** paths:
+ /**
* List of all files to wipe.
*/
public List<string> paths {
@@ -45,10 +44,10 @@ namespace Gsd
this.path = Config.SRM_PATH;
}
- /** add_path:
- * @path: a path to securely remove.
- *
+ /**
* Adds a path to the list of paths to remove.
+ *
+ * @param path a path to securely remove.
*/
public void add_path (string path)
requires (! this.busy)
@@ -56,16 +55,15 @@ namespace Gsd
this._paths.append (path);
}
- /** remove_path:
- * @path: a path already added you want to remove from the list.
- *
+ /**
* Removes a path from the list of paths to wipe.
- * <warning>
- * This is NOT a filter for files not to wipe! It only remove a path
- * previously added with add_path() from the list of paths to wipe, it
- * does not prevent wiping of a path if the directory containing it is
- * in the list of paths to wipe.
- * </warning>
+ *
+ * Note that this is NOT a filter for files not to wipe! It only remove a
+ * path previously added with add_path() from the list of paths to wipe, it
+ * does not prevent wiping of a path if the directory containing it is in
+ * the list of paths to wipe.
+ *
+ * @param path a path already added you want to remove from the list.
*/
public void remove_path (string path)
requires (! this.busy)
diff --git a/gsecuredelete/fill-operation.vala b/gsecuredelete/fill-operation.vala
index cf22a46..a961549 100644
--- a/gsecuredelete/fill-operation.vala
+++ b/gsecuredelete/fill-operation.vala
@@ -19,26 +19,30 @@
namespace Gsd
{
- /** FillOperation:
- *
- * Wrapper for `sfill`.
+ /**
+ * Wrapper for //sfill//.
*/
public class FillOperation : ZeroableOperation
{
/**
- * WipeMode:
- *
- * @FULL: wipe both free inode and data free space.
- * @INODES: wipe only free inode space (not free data space)
- * @DATA: wipe only free data space (not free inode space)
+ * What to wipe
*/
public enum WipeMode {
+ /**
+ * wipe both free inode and data free space.
+ */
FULL,
+ /**
+ * wipe only free inode space (not free data space)
+ */
INODES,
+ /**
+ * wipe only free data space (not free inode space)
+ */
DATA
}
- /** FillOperation:wipe_mode
+ /**
* The wiping mode
*/
public WipeMode wipe_mode {
@@ -46,8 +50,9 @@ namespace Gsd
set;
default = WipeMode.FULL;
}
- /** FillOperation:directory:
- * The directory to fill (must of course be on the filesystem to clean).
+ /**
+ * The directory to fill (must of course be on the filesystem to clean)
+ *
* I recommend you not to fill in a useful directory but inside a new and
* clean one. This can be useful if the filling is interrupted, voluntarily
* or not, as this process may spawn a lot of files that might not be
@@ -108,15 +113,14 @@ namespace Gsd
this.directory = null;
}
- /** run:
- * @directory: the directory to fill. It is exactly the same as setting
- * the FillOperation:directory property, just a convenience
- * possibility.
- * @watch_interval: See AsyncOperation.run()
- *
+ /**
* Launches a secure filling asynchronously.
*
- * Returns: whether subprocess started successfully.
+ * @param directory the directory to fill. It is exactly the same as setting
+ * the FillOperation:directory property, just a convenience possibility.
+ * @param watch_interval See AsyncOperation.run()
+ *
+ * @return whether subprocess started successfully.
*/
public new bool run (string? directory = null,
uint watch_interval = 100)
@@ -128,14 +132,13 @@ namespace Gsd
return base.run (watch_interval);
}
- /** run_sync:
- * @directory: the directory to fill. It is exactly the same as setting
- * the FillOperation:directory property, just a convenience
- * possibility.
- *
+ /**
* Launches a secure filling synchronously.
*
- * Returns: whether filling was successful.
+ * @param directory the directory to fill. It is exactly the same as setting
+ * the FillOperation:directory property, just a convenience possibility.
+ *
+ * @return whether filling was successful.
*/
public new bool run_sync (string? directory = null)
throws SpawnError, AsyncOperationError
diff --git a/gsecuredelete/mem-operation.vala b/gsecuredelete/mem-operation.vala
index 035eeaa..04faa45 100644
--- a/gsecuredelete/mem-operation.vala
+++ b/gsecuredelete/mem-operation.vala
@@ -24,9 +24,8 @@ namespace Gsd
* * test
*/
- /** MemOperation:
- *
- * Wrapper for `smem`.
+ /**
+ * Wrapper for //smem//.
*/
public class MemOperation : SecureDeleteOperation
{
diff --git a/gsecuredelete/securedelete-operation.vala b/gsecuredelete/securedelete-operation.vala
index aac98e9..f58d4e6 100644
--- a/gsecuredelete/securedelete-operation.vala
+++ b/gsecuredelete/securedelete-operation.vala
@@ -22,36 +22,43 @@ using GLib;
namespace Gsd
{
/**
- * SecureDeleteOperation:
+ * An AsyncOperation subclass to implement SecureDelete operations.
*
- * A subclass of AsyncOperation designed to be the base class for all
- * SecureDelete operations. It implements things that are the same for all
- * SecureDelete operators.
+ * This class implements everything that is shared by all SecureDelete
+ * operators.
*/
public abstract class SecureDeleteOperation : AsyncOperation
{
/**
- * Mode:
- *
- * Security mode:
- * @NORMAL: normal mode (default) (38 passes)
- * @INSECURE: less security (-l option) (2 passes)
- * @VERY_INSECURE: even less security (-ll option) (1 pass)
+ * Security mode
*/
public enum Mode {
+ /**
+ * normal mode (default) (38 passes)
+ */
NORMAL,
+ /**
+ * less security (-l option) (2 passes)
+ */
INSECURE,
+ /**
+ * even less security (-ll option) (1 pass)
+ */
VERY_INSECURE
}
- /** Whether to use fast (and insecure) work mode (-f option). */
+ /**
+ * Whether to use fast (and insecure) work mode (-f option).
+ */
public bool fast {
get;
set;
default = false;
}
- /** The security mode */
+ /**
+ * The security mode
+ */
public Mode mode {
get;
set;
@@ -141,10 +148,11 @@ namespace Gsd
return progress;
}
- /** run:
+ /**
* Runs a SecureDelete operator asynchronously.
*
- * Returns: whether operation started successfully.
+ * @param watch_interval See AsyncOperation.run()
+ * @return whether operation started successfully.
*/
public new bool run (uint watch_interval = 100)
throws SpawnError, AsyncOperationError
@@ -152,10 +160,10 @@ namespace Gsd
return base.run (null, 0, watch_interval);
}
- /** run_sync:
+ /**
* Runs a SecureDelete operator synchronously.
*
- * Returns: whether operation was successful.
+ * @return whether operation was successful.
*/
public new bool run_sync ()
throws SpawnError, AsyncOperationError
diff --git a/gsecuredelete/swap-operation.vala b/gsecuredelete/swap-operation.vala
index 63501a0..33737e9 100644
--- a/gsecuredelete/swap-operation.vala
+++ b/gsecuredelete/swap-operation.vala
@@ -19,13 +19,12 @@
namespace Gsd
{
- /** SwapOperation:
- *
- * Wrapper for `sswap`.
+ /**
+ * Wrapper for //sswap//.
*/
public class SwapOperation : ZeroableOperation
{
- /** SwapOperation:device:
+ /**
* The swap device to wipe.
*/
public string device {
@@ -36,6 +35,7 @@ namespace Gsd
/**
* Whether to throw an error if the swap is detected as being currently
* used.
+ *
* This may be useful because doing the operation on an in-use swap device
* may crash the system.
*/
@@ -111,14 +111,14 @@ namespace Gsd
this.device = null;
}
- /** run:
- * @device: the swap device to wipe. It is exactly the same as setting the
- * the SwapOperation:device property, just a convenience shortcut.
- * @watch_interval: See AsyncOperation.run()
- *
+ /**
* Launches a secure wiping of a swap device asynchronously.
*
- * Returns: whether subprocess started successfully.
+ * @param device the swap device to wipe. It is exactly the same as setting
+ * the SwapOperation:device property, just a convenience shortcut.
+ * @param watch_interval See AsyncOperation.run()
+ *
+ * @return whether subprocess started successfully.
*/
public new bool run (string? device = null,
uint watch_interval = 100)
@@ -130,13 +130,13 @@ namespace Gsd
return base.run (watch_interval);
}
- /** run_sync:
- * @device: the swap device to wipe. It is exactly the same as setting the
- * the SwapOperation:device property, just a convenience shortcut.
- *
+ /**
* Launches a secure wiping of a swap device synchronously.
*
- * Returns: whether wiping of the swap device succeed.
+ * @param device the swap device to wipe. It is exactly the same as setting
+ * the SwapOperation:device property, just a convenience shortcut.
+ *
+ * @return whether wiping of the swap device succeed.
*/
public new bool run_sync (string? device = null)
throws SpawnError, AsyncOperationError
diff --git a/gsecuredelete/utils.vala b/gsecuredelete/utils.vala
index a2ad30b..6792655 100644
--- a/gsecuredelete/utils.vala
+++ b/gsecuredelete/utils.vala
@@ -19,35 +19,40 @@
namespace Gsd
{
- /** FDError:
- *
+ /**
* Error domain for the FD namespace functions. It is mainly a wrapper around
* some errnos to have exceptions for them.
- *
- * @KILL_ERROR: A call to Posix.kill() failed.
- * @READ_ERROR: A call to Posix.read() failed.
- * @SELECT_ERROR: A call to Posix.select() failed.
- * @WAITPID_ERROR: A call to Posix.waitpid() failed.
*/
internal errordomain FDError {
+ /**
+ * A call to Posix.kill() failed.
+ */
KILL_ERROR,
+ /**
+ * A call to Posix.read() failed.
+ */
READ_ERROR,
+ /**
+ * A call to Posix.select() failed.
+ */
SELECT_ERROR,
+ /**
+ * A call to Posix.waitpid() failed.
+ */
WAITPID_ERROR,
}
namespace FD
{
- /** read_ready:
- * @fd: a file descriptor
- * @error: return location for an error string on error, or NULL to ignore
- * errors.
+ /**
+ * Gets whether a file descriptor is ready to be read or not.
+ *
+ * Being ready means that reading data from it would not be blocking, as
+ * there is data to be read.
*
- * Gets whether a file descriptor is ready to be read or not. Ready means
- * that reading data from it would not be blocking, as there is data to be
- * read.
+ * @param fd a file descriptor
*
- * Returns: %TRUE if the file is read, %FALSE otherwise.
+ * @return %TRUE if the file is read, %FALSE otherwise.
*/
internal bool read_ready (int fd)
throws FDError
@@ -72,14 +77,15 @@ namespace Gsd
return ready;
}
- /** read_string:
- * @fd: a file descriptor
- * @n_bytes: number of bytes to read from @fd, or -1 to read all @fd
- *
+ /**
* Reads content of a file as a string.
+ *
* This function may only work with text data.
*
- * Returns: a newly allocated string containing data in @fd.
+ * @param fd a file descriptor
+ * @param n_bytes number of bytes to read from @fd, or -1 to read all @fd
+ *
+ * @return a newly allocated string containing data in @fd.
*/
internal static string? read_string (int fd,
ssize_t n_bytes = -1)
@@ -135,21 +141,21 @@ namespace Gsd
return (string?) (owned) buf;
}
- /** count_ready_bytes:
- * @fd: a valid file descriptor
- * @byte: the byte to cont in @fd
- * @bufsize: the size of the buffer used to cache the file's content.
- * Tweaking it may improve the performances with different amount
- * of data in @fd: the better value is the closer to the total
- * number of bytes that will be read (the size of the file's
- * content) or a multiple of it if it is a too big value to be
- * reasonably allocated at once.
- *
+ /**
* Counts the number of occurrence of a given byte in a file descriptor.
+ *
* This function is non-blocking and returns 0 if there is no data in the
* buffer rather than blocking waiting for data.
*
- * Returns: the number of occurrences of @byte in @fd.
+ * @param fd a valid file descriptor
+ * @param byte the byte to cont in @fd
+ * @param bufsize the size of the buffer used to cache the file's content.
+ * Tweaking it may improve the performances with different amount of data
+ * in @fd: the better value is the closer to the total number of bytes
+ * that will be read (the size of the file's content) or a multiple of it
+ * if it is a too big value to be reasonably allocated at once.
+ *
+ * @return the number of occurrences of @byte in @fd.
*/
internal uint count_ready_bytes (int fd,
int byte,
diff --git a/gsecuredelete/zeroable-operation.vala b/gsecuredelete/zeroable-operation.vala
index 9174e1d..473eb22 100644
--- a/gsecuredelete/zeroable-operation.vala
+++ b/gsecuredelete/zeroable-operation.vala
@@ -23,17 +23,14 @@ namespace Gsd
{
/**
- * ZeroableOperation:
+ * A SecureDeleteOperation subclass to implment zeroable operations
*
- * A subclass of SecureDeleteOperation designed to be the base class for all
- * SecureDelete operations that support wiping with zeros only as the last
- * pass.
+ * A base class for all SecureDelete operations that support wiping with zeros
+ * as the last pass.
*/
public abstract class ZeroableOperation : SecureDeleteOperation
{
/**
- * zeroise:
- *
* Whether to wipe with zeros at the last pass instead of random data.
*/
public bool zeroise {
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/libgsecuredelete.git
More information about the Pkg-privacy-commits
mailing list