From e7255c63d78f47fdafad0578245dd8ac4724e8ae Mon Sep 17 00:00:00 2001 From: Iustin Pop 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=, 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=, meaning create a copy\n" - " of an existing ACL instance\n" - " - mode=, 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