From e7255c63d78f47fdafad0578245dd8ac4724e8ae Mon Sep 17 00:00:00 2001
From: Iustin Pop <iusty@k1024.org>
Date: Sun, 13 May 2012 03:38:11 +0200
Subject: [PATCH] Rework documentation style to RST/Sphinx custom
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit
Hrmm, editing it in C source code is ugly⦠but the docs are pretty!
---
acl.c | 296 +++++++++++++++++++++++++++++++++++-----------------------
1 file changed, 178 insertions(+), 118 deletions(-)
diff --git a/acl.c b/acl.c
index 837a73d..7a7a085 100644
--- a/acl.c
+++ b/acl.c
@@ -218,29 +218,30 @@ static PyObject* ACL_str(PyObject *obj) {
#ifdef HAVE_LINUX
static char __to_any_text_doc__[] =
+ "to_any_text([prefix='', separator='n', options=0])\n"
"Convert the ACL to a custom text format.\n"
"\n"
- "This method encapsulates the acl_to_any_text function. It allows a \n"
- "customized text format to be generated for the ACL. See\n"
- "acl_to_any_text(3) for more details.\n"
+ "This method encapsulates the ``acl_to_any_text()`` function.\n"
+ "It allows a customized text format to be generated for the ACL. See\n"
+ ":manpage:`acl_to_any_text(3)` for more details.\n"
"\n"
- "Parameters:\n\n"
- "- prefix: if given, this string will be prepended to all lines\n"
- "- separator: a single character (defaults to '\\n'); this will be\n"
- " used to separate the entries in the ACL\n"
- "- options: a bitwise combination of:\n"
- "\n\n"
- " - ``TEXT_ABBREVIATE``: use 'u' instead of 'user', 'g' instead of\n"
- " 'group', etc.\n"
- " - ``TEXT_NUMERIC_IDS``: User and group IDs are included as decimal\n"
- " numbers instead of names\n"
- " - ``TEXT_SOME_EFFECTIVE``: Include comments denoting the effective\n"
- " permissions when some are masked\n"
- " - ``TEXT_ALL_EFFECTIVE``: Include comments after all ACL entries\n"
- " affected by an ACL_MASK entry\n"
- " - ``TEXT_SMART_INDENT``: Used in combination with the _EFFECTIVE\n"
- " options, this will ensure that comments are aligned to the\n"
- " fourth tab position (assuming one tab equals eight spaces)\n"
+ ":param string prefix: if given, this string will be pre-pended to\n"
+ " all lines\n"
+ ":param string separator: a single character (defaults to '\\n'); this will"
+ " be used to separate the entries in the ACL\n"
+ ":param options: a bitwise combination of:\n\n"
+ " - :py:data:`TEXT_ABBREVIATE`: use 'u' instead of 'user', 'g' \n"
+ " instead of 'group', etc.\n"
+ " - :py:data:`TEXT_NUMERIC_IDS`: User and group IDs are included as\n"
+ " decimal numbers instead of names\n"
+ " - :py:data:`TEXT_SOME_EFFECTIVE`: Include comments denoting the\n"
+ " effective permissions when some are masked\n"
+ " - :py:data:`TEXT_ALL_EFFECTIVE`: Include comments after all ACL\n"
+ " entries affected by an ACL_MASK entry\n"
+ " - :py:data:`TEXT_SMART_INDENT`: Used in combination with the\n"
+ " _EFFECTIVE options, this will ensure that comments are aligned\n"
+ " to the fourth tab position (assuming one tab equals eight spaces)\n"
+ ":rtype: string\n"
;
/* Converts the acl to a custom text format */
@@ -274,18 +275,20 @@ static char __check_doc__[] =
"Check the ACL validity.\n"
"\n"
"This is a non-portable, Linux specific extension that allow more\n"
- "information to be retrieved in case an ACL is not valid than the\n"
- "validate() method.\n"
+ "information to be retrieved in case an ACL is not valid than via the\n"
+ ":py:func:`valid` method.\n"
"\n"
"This method will return either False (the ACL is valid), or a tuple\n"
"with two elements. The first element is one of the following\n"
"constants:\n\n"
- " - ACL_MULTI_ERROR: The ACL contains multiple entries that have a\n"
- " tag type that may occur at most once\n"
- " - ACL_DUPLICATE_ERROR: The ACL contains multiple ACL_USER or\n"
- " ACL_GROUP entries with the same ID\n"
- " - ACL_MISS_ERROR: A required entry is missing\n"
- " - ACL_ENTRY_ERROR: The ACL contains an invalid entry tag type\n"
+ " - :py:data:`ACL_MULTI_ERROR`: The ACL contains multiple entries that\n"
+ " have a tag type that may occur at most once\n"
+ " - :py:data:`ACL_DUPLICATE_ERROR`: The ACL contains multiple \n"
+ " :py:data:`ACL_USER` or :py:data:`ACL_GROUP` entries with the\n"
+ " same ID\n"
+ " - :py:data:`ACL_MISS_ERROR`: A required entry is missing\n"
+ " - :py:data:`ACL_ENTRY_ERROR`: The ACL contains an invalid entry\n"
+ " tag type\n"
"\n"
"The second element of the tuple is the index of the entry that is\n"
"invalid (in the same order as by iterating over the ACL entry)\n"
@@ -344,7 +347,9 @@ static char __equiv_mode_doc__[] =
"This is a non-portable, Linux specific extension that checks\n"
"if the ACL is a basic ACL and returns the corresponding mode.\n"
"\n"
- "An IOerror exception will be raised if the ACL is an extended ACL\n"
+ ":rtype: integer\n"
+ ":raise IOError: An IOerror exception will be raised if the ACL is\n"
+ " an extended ACL.\n"
;
/* The acl_equiv_mode method */
@@ -367,13 +372,13 @@ static int ACL_nocmp(PyObject* o1, PyObject* o2) {
/* Custom methods */
static char __applyto_doc__[] =
+ "applyto(item[, flag=ACL_TYPE_ACCESS])\n"
"Apply the ACL to a file or filehandle.\n"
"\n"
- "Parameters:\n"
- " - either a filename or a file-like object or an integer; this\n"
- " represents the filesystem object on which to act\n"
- " - optional flag representing the type of ACL to set, either\n"
- " ACL_TYPE_ACCESS (default) or ACL_TYPE_DEFAULT\n"
+ ":param item: either a filename or a file-like object or an integer;\n"
+ " this represents the filesystem object on which to act\n"
+ ":param flag: optional flag representing the type of ACL to set, either\n"
+ " :py:data:`ACL_TYPE_ACCESS` (default) or :py:data:`ACL_TYPE_DEFAULT`\n"
;
/* Applies the ACL to a file */
@@ -419,25 +424,32 @@ static char __valid_doc__[] =
"Test the ACL for validity.\n"
"\n"
"This method tests the ACL to see if it is a valid ACL\n"
- "in terms of the filesystem. More precisely, it checks that:\n"
+ "in terms of the file-system. More precisely, it checks that:\n"
"\n"
"The ACL contains exactly one entry with each of the\n"
- "ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries\n"
- "with ACL_USER and ACL_GROUP tag types may appear zero or more\n"
- "times in an ACL. An ACL that contains entries of ACL_USER or\n"
- "ACL_GROUP tag types must contain exactly one entry of the \n"
- "ACL_MASK tag type. If an ACL contains no entries of\n"
- "ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.\n"
+ ":py:data:`ACL_USER_OBJ`, :py:data:`ACL_GROUP_OBJ`, and \n"
+ ":py:data:`ACL_OTHER` tag types. Entries\n"
+ "with :py:data:`ACL_USER` and :py:data:`ACL_GROUP` tag types may\n"
+ "appear zero or more\n"
+ "times in an ACL. An ACL that contains entries of :py:data:`ACL_USER` or\n"
+ ":py:data:`ACL_GROUP` tag types must contain exactly one entry of the \n"
+ ":py:data:`ACL_MASK` tag type. If an ACL contains no entries of\n"
+ ":py:data:`ACL_USER` or :py:data:`ACL_GROUP` tag types, the\n"
+ ":py:data:`ACL_MASK` entry is optional.\n"
"\n"
"All user ID qualifiers must be unique among all entries of\n"
- "the ACL_USER tag type, and all group IDs must be unique among all\n"
- "entries of ACL_GROUP tag type.\n"
+ "the :py:data:`ACL_USER` tag type, and all group IDs must be unique\n"
+ "among all entries of :py:data:`ACL_GROUP` tag type.\n"
"\n"
"The method will return 1 for a valid ACL and 0 for an invalid one.\n"
- "This has been chosen because the specification for acl_valid in\n"
- "the POSIX.1e standard documents only one possible value for errno\n"
+ "This has been chosen because the specification for\n"
+ ":manpage:`acl_valid(3)`\n"
+ "in the POSIX.1e standard documents only one possible value for errno\n"
"in case of an invalid ACL, so we can't differentiate between\n"
"classes of errors. Other suggestions are welcome.\n"
+ "\n"
+ ":return: 0 or 1\n"
+ ":rtype: integer\n"
;
/* Checks the ACL for validity */
@@ -549,8 +561,7 @@ static char __ACL_delete_entry_doc__[] =
"\n"
".. note:: Only available with level 2.\n"
"\n"
- "Parameters:\n\n"
- " - the Entry object which should be deleted; note that after\n"
+ ":param entry: the Entry object which should be deleted; note that after\n"
" this function is called, that object is unusable any longer\n"
" and should be deleted\n"
;
@@ -575,12 +586,14 @@ static char __ACL_calc_mask_doc__[] =
"Compute the file group class mask.\n"
"\n"
"The calc_mask() method calculates and sets the permissions \n"
- "associated with the ACL_MASK Entry of the ACL.\n"
+ "associated with the :py:data:`ACL_MASK` Entry of the ACL.\n"
"The value of the new permissions is the union of the permissions \n"
- "granted by all entries of tag type ACL_GROUP, ACL_GROUP_OBJ, or \n"
- "ACL_USER. If the ACL already contains an ACL_MASK entry, its \n"
- "permissions are overwritten; if it does not contain an ACL_MASK \n"
- "Entry, one is added.\n"
+ "granted by all entries of tag type :py:data:`ACL_GROUP`, \n"
+ ":py:data:`ACL_GROUP_OBJ`, or \n"
+ ":py:data:`ACL_USER`. If the ACL already contains an :py:data:`ACL_MASK`\n"
+ "entry, its \n"
+ "permissions are overwritten; if it does not contain an \n"
+ ":py:data:`ACL_MASK` Entry, one is added.\n"
"\n"
"The order of existing entries in the ACL is undefined after this \n"
"function.\n"
@@ -599,13 +612,17 @@ static PyObject* ACL_calc_mask(PyObject *obj, PyObject *args) {
}
static char __ACL_append_doc__[] =
+ "append([entry])\n"
"Append a new Entry to the ACL and return it.\n"
"\n"
"This is a convenience function to create a new Entry \n"
"and append it to the ACL.\n"
"If a parameter of type Entry instance is given, the \n"
"entry will be a copy of that one (as if copied with \n"
- "Entry.copy()), otherwise, the new entry will be empty.\n"
+ ":py:func:`Entry.copy`), otherwise, the new entry will be empty.\n"
+ "\n"
+ ":rtype: :py:class:`Entry`\n"
+ ":returns: the newly created entry\n"
;
/* Convenience method to create a new Entry */
@@ -896,13 +913,12 @@ static int Entry_set_permset(PyObject* obj, PyObject* value, void* arg) {
static char __Entry_copy_doc__[] =
"copy(src)\n"
- "Copy an ACL entry.\n"
+ "Copies an ACL entry.\n"
"\n"
"This method sets all the parameters to those of another\n"
"entry (either of the same ACL or belonging to another ACL).\n"
"\n"
- "Parameters:\n\n"
- " - src, instance of type Entry\n"
+ ":param Entry src: instance of type Entry\n"
;
/* Sets all the entry parameters to another entry */
@@ -985,7 +1001,7 @@ static PyObject* Permset_str(PyObject *obj) {
}
static char __Permset_clear_doc__[] =
- "Clear all permissions from the permission set.\n"
+ "Clears all permissions from the permission set.\n"
;
/* Clears all permissions from the permset */
@@ -1033,19 +1049,17 @@ static int Permset_set_right(PyObject* obj, PyObject* value, void* arg) {
}
static char __Permset_add_doc__[] =
+ "add(perm)\n"
"Add a permission to the permission set.\n"
"\n"
- "The add() function adds the permission contained in \n"
+ "This function adds the permission contained in \n"
"the argument perm to the permission set. An attempt \n"
"to add a permission that is already contained in the \n"
"permission set is not considered an error.\n"
"\n"
- "Parameters:\n\n"
- " - perm: a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...)\n"
- "\n"
- "Return value: None\n"
- "\n"
- "Can raise: IOError\n"
+ ":param perm: a permission (:py:data:`ACL_WRITE`, :py:data:`ACL_READ`,\n"
+ " :py:data:`ACL_EXECUTE`, ...)\n"
+ ":raises IOError: in case the argument is not a valid descriptor\n"
;
static PyObject* Permset_add(PyObject* obj, PyObject* args) {
@@ -1067,17 +1081,14 @@ static char __Permset_delete_doc__[] =
"delete(perm)\n"
"Delete a permission from the permission set.\n"
"\n"
- "The delete() function deletes the permission contained in \n"
- "the argument perm from the permission set. An attempt \n"
+ "This function deletes the permission contained in \n"
+ "the argument perm from the permission set. An attempt \n"
"to delete a permission that is not contained in the \n"
"permission set is not considered an error.\n"
"\n"
- "Parameters:\n\n"
- " - perm: a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...)\n"
- "\n"
- "Return value: None\n"
- "\n"
- "Can raise: IOError\n"
+ ":param perm: a permission (:py:data:`ACL_WRITE`, :py:data:`ACL_READ`,\n"
+ " :py:data:`ACL_EXECUTE`, ...)\n"
+ ":raises IOError: in case the argument is not a valid descriptor\n"
;
static PyObject* Permset_delete(PyObject* obj, PyObject* args) {
@@ -1102,12 +1113,10 @@ static char __Permset_test_doc__[] =
"The test() function tests if the permission represented by\n"
"the argument perm exists in the permission set.\n"
"\n"
- "Parameters:\n\n"
- " - perm: a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...)\n"
- "\n"
- "Return value: Boolean\n"
- "\n"
- "Can raise: IOError\n"
+ ":param perm: a permission (:py:data:`ACL_WRITE`, :py:data:`ACL_READ`,\n"
+ " :py:data:`ACL_EXECUTE`, ...)\n"
+ ":rtype: Boolean\n"
+ ":raises IOError: in case the argument is not a valid descriptor\n"
;
static PyObject* Permset_test(PyObject* obj, PyObject* args) {
@@ -1134,24 +1143,25 @@ static PyObject* Permset_test(PyObject* obj, PyObject* args) {
static char __ACL_Type_doc__[] =
"Type which represents a POSIX ACL\n"
"\n"
- "Parameters (only one keyword parameter should be provided):\n"
- " - file=\"...\", meaning create ACL representing\n"
- " the access ACL of that file\n"
- " - filedef=\"...\", meaning create ACL representing\n"
- " the default ACL of that directory\n"
- " - fd=<int>, meaning create ACL representing\n"
- " the access ACL of that file descriptor\n"
- " - text=\"...\", meaning create ACL from a \n"
+ ".. note:: only one keyword parameter should be provided\n"
+ "\n"
+ ":param string file: creates an ACL representing\n"
+ " the access ACL of the specified file\n"
+ ":param string filedef: creates an ACL representing\n"
+ " the default ACL of the given directory\n"
+ ":param int fd: creates an ACL representing\n"
+ " the access ACL of the given file descriptor\n"
+ ":param string text: creates an ACL from a \n"
" textual description\n"
- " - acl=<ACL instance>, meaning create a copy\n"
- " of an existing ACL instance\n"
- " - mode=<int>, meaning create an ACL from a numeric mode\n"
+ ":param ACL acl: creates a copy of an existing ACL instance\n"
+ ":param int mode: creates an ACL from a numeric mode\n"
" (e.g. mode=0644) (this is valid only when the C library\n"
" provides the acl_from_mode call)\n"
"\n"
- "If no parameters are passed, create an empty ACL; this\n"
+ "If no parameters are passed, an empty ACL will be created; this\n"
"makes sense only when your OS supports ACL modification\n"
- "(i.e. it implements full POSIX.1e support)\n"
+ "(i.e. it implements full POSIX.1e support), otherwise the ACL won't\n"
+ "be useful.\n"
;
/* ACL type methods */
@@ -1247,21 +1257,21 @@ static char __Entry_tagtype_doc__[] =
"The tag type of the current entry\n"
"\n"
"This is one of:\n"
- " - ACL_UNDEFINED_TAG\n"
- " - ACL_USER_OBJ\n"
- " - ACL_USER\n"
- " - ACL_GROUP_OBJ\n"
- " - ACL_GROUP\n"
- " - ACL_MASK\n"
- " - ACL_OTHER\n"
+ " - :py:data:`ACL_UNDEFINED_TAG`\n"
+ " - :py:data:`ACL_USER_OBJ`\n"
+ " - :py:data:`ACL_USER`\n"
+ " - :py:data:`ACL_GROUP_OBJ`\n"
+ " - :py:data:`ACL_GROUP`\n"
+ " - :py:data:`ACL_MASK`\n"
+ " - :py:data:`ACL_OTHER`\n"
;
static char __Entry_qualifier_doc__[] =
"The qualifier of the current entry\n"
"\n"
- "If the tag type is ACL_USER, this should be a user id.\n"
- "If the tag type if ACL_GROUP, this should be a group id.\n"
- "Else, it doesn't matter.\n"
+ "If the tag type is :py:data:`ACL_USER`, this should be a user id.\n"
+ "If the tag type if :py:data:`ACL_GROUP`, this should be a group id.\n"
+ "Else it doesn't matter.\n"
;
static char __Entry_parent_doc__[] =
@@ -1293,6 +1303,7 @@ static char __Entry_Type_doc__[] =
" >>> e = myACL.append() # another way for doing the same thing\n"
"\n"
"or by:\n"
+ "\n"
" >>> for entry in myACL:\n"
" ... print entry\n"
"\n"
@@ -1357,27 +1368,30 @@ static PyMethodDef Permset_methods[] = {
};
static char __Permset_execute_doc__[] =
- "Execute permsission\n"
+ "Execute permission property\n"
"\n"
- "This is a convenience method of access; the \n"
+ "This is a convenience method of retrieving and setting the execute\n"
+ "permission in the permission set; the \n"
"same effect can be achieved using the functions\n"
"add(), test(), delete(), and those can take any \n"
"permission defined by your platform.\n"
;
static char __Permset_read_doc__[] =
- "Read permsission\n"
+ "Read permission property\n"
"\n"
- "This is a convenience method of access; the \n"
+ "This is a convenience method of retrieving and setting the read\n"
+ "permission in the permission set; the \n"
"same effect can be achieved using the functions\n"
"add(), test(), delete(), and those can take any \n"
"permission defined by your platform.\n"
;
static char __Permset_write_doc__[] =
- "Write permission\n"
+ "Write permission property\n"
"\n"
- "This is a convenience method of access; the \n"
+ "This is a convenience method of retrieving and setting the write\n"
+ "permission in the permission set; the \n"
"same effect can be achieved using the functions\n"
"add(), test(), delete(), and those can take any \n"
"permission defined by your platform.\n"
@@ -1468,8 +1482,7 @@ static char __deletedef_doc__[] =
"a directory (the ACL which will be ANDed with the mode\n"
"parameter to the open, creat functions).\n"
"\n"
- "Parameters:\n\n"
- " - path: the directory whose default ACL should be deleted\n"
+ ":param string path: the directory whose default ACL should be deleted\n"
;
/* Deletes the default ACL from a directory */
@@ -1492,11 +1505,10 @@ static PyObject* aclmodule_delete_default(PyObject* obj, PyObject* args) {
#ifdef HAVE_LINUX
static char __has_extended_doc__[] =
"has_extended(item)\n"
- "Check if a file or filehandle has an extended ACL.\n"
+ "Check if a file or file handle has an extended ACL.\n"
"\n"
- "Parameters:\n"
- " - item: either a filename or a file-like object or an integer; this\n"
- " represents the filesystem object on which to act\n"
+ ":param item: either a file name or a file-like object or an integer;\n"
+ " it represents the file-system object on which to act\n"
;
/* Check for extended ACL a file or fd */
@@ -1549,6 +1561,7 @@ static PyMethodDef aclmodule_methods[] = {
static char __posix1e_doc__[] =
"POSIX.1e ACLs manipulation\n"
+ "==========================\n"
"\n"
"This module provides support for manipulating POSIX.1e ACLS\n"
"\n"
@@ -1565,11 +1578,12 @@ static char __posix1e_doc__[] =
"\n"
"The existence of level 2 support and other extensions can be\n"
"checked by the constants:\n\n"
- " - ``HAS_ACL_ENTRY`` for level 2 and the Entry/Permset classes\n"
- " - ``HAS_ACL_FROM_MODE`` for ACL(mode=...) usage\n"
- " - ``HAS_ACL_CHECK`` for the ACL().check function\n"
- " - ``HAS_EXTENDED_CHECK`` for the module-level has_extended function\n"
- " - ``HAS_EQUIV_MODE`` for the ACL().equiv_mode method\n"
+ " - :py:data:`HAS_ACL_ENTRY` for level 2 and the Entry/Permset classes\n"
+ " - :py:data:`HAS_ACL_FROM_MODE` for ``ACL(mode=...)`` usage\n"
+ " - :py:data:`HAS_ACL_CHECK` for the :py:func:`ACL.check` function\n"
+ " - :py:data:`HAS_EXTENDED_CHECK` for the module-level\n"
+ " :py:func:`has_extended` function\n"
+ " - :py:data:`HAS_EQUIV_MODE` for the :py:func:`ACL.equiv_mode` method\n"
"\n"
"Example:\n"
"\n"
@@ -1593,6 +1607,52 @@ static char __posix1e_doc__[] =
"other::---\n"
">>>\n"
"\n"
+ ".. py:data:: ACL_USER\n\n"
+ " Denotes a specific user entry in an ACL.\n"
+ "\n"
+ ".. py:data:: ACL_USER_OBJ\n\n"
+ " Denotes the user owner entry in an ACL.\n"
+ "\n"
+ ".. py:data:: ACL_GROUP\n\n"
+ " Denotes the a group entry in an ACL.\n"
+ "\n"
+ ".. py:data:: ACL_GROUP_OBJ\n\n"
+ " Denotes the group owner entry in an ACL.\n"
+ "\n"
+ ".. py:data:: ACL_OTHER\n\n"
+ " Denotes the 'others' entry in an ACL.\n"
+ "\n"
+ ".. py:data:: ACL_MASK\n\n"
+ " Denotes the mask entry in an ACL, representing the maximum\n"
+ " access granted other users, the owner group and other groups.\n"
+ "\n"
+ ".. py:data:: ACL_UNDEFINED_TAG\n\n"
+ " An undefined tag in an ACL.\n"
+ "\n"
+ ".. py:data:: ACL_READ\n\n"
+ " Read permission in a permission set.\n"
+ "\n"
+ ".. py:data:: ACL_WRITE\n\n"
+ " Write permission in a permission set.\n"
+ "\n"
+ ".. py:data:: ACL_EXECUTE\n\n"
+ " Execute permission in a permission set.\n"
+ "\n"
+ ".. py:data:: HAS_ACL_ENTRY\n\n"
+ " denotes support for level 2 and the Entry/Permset classes\n"
+ "\n"
+ ".. py:data:: HAS_ACL_FROM_MODE\n\n"
+ " denotes support for building an ACL from an octal mode\n"
+ "\n"
+ ".. py:data:: HAS_ACL_CHECK\n\n"
+ " denotes support for extended checks of an ACL's validity\n"
+ "\n"
+ ".. py:data:: HAS_EXTENDED_CHECK\n\n"
+ " denotes support for checking whether an ACL is basic or extended\n"
+ "\n"
+ ".. py:data:: HAS_EQUIV_MODE\n\n"
+ " denotes support for the equiv_mode function\n"
+ "\n"
;
#ifdef IS_PY3K
--
2.39.5