Re: [pacman-dev] [PATCH 2/2] Docs docs docs and more docs

[Allan McRae]

On 26/1/20 5:01 pm, morganamilo wrote:
> Write docs for every public alpm member and expand on the existing
> documentation for other members.
> 
> ---
> 
> The entire .h file has basically been restructed. The best way to see
> the end result is either to read the generated man pages or enabled html
> and view the generated html.
> 
> Also note alpm_list is still not documented.

Awesome work!  Great that someone is taking this on.

Here are my comments...   Often with little context, but you can search
for what I have left.


+
+ * If the database is already preasant in the dbpath then it will be
usable. Otherwise,

present

+ * the database needs to be downloaded using \link alpm_db_update
\endlink. Even if the

s/. E/, e/

+   /** Permmision denied */

Typo

+   /** Handle should be null */
ALPM_ERR_HANDLE_NULL,
+   /** Handle should not be null */
ALPM_ERR_HANDLE_NOT_NULL,

I think these comments are switched

+   /** Database should not be null */
ALPM_ERR_DB_NULL,
+   /** Database should be null */
ALPM_ERR_DB_NOT_NULL,

And again

+   /** Fauked to write to the database */
Failed.

+   /** Fauked to remove entry from database */
Failed


+   /** A transaction has not been initialized */
ALPM_ERR_TRANS_NULL,
+   /** A transaction has not been initialized */
ALPM_ERR_TRANS_NOT_INITIALIZED,

Distinguish these

+   /** Package is in ignorepkg */
ALPM_ERR_PKG_IGNORED,

Or --ignore was used.  Just "Package is ignored"

+   /** Files conflict. */
ALPM_ERR_FILE_CONFLICTS,

Only one with trailing fullstop.

+   /** A character representing the  encryption algorithm used by the
public key

Double space.

+   /** The amount of results in the array */

The number of

+   /** The conflict results with a another target in the transaction */

The conflict is with another ...

+   /** A hash of the name, used to speed up dependnecy checks */

Typo

+   /** The name of the package that also owns the file if there is one*/

Space before comment end.

+/** When a hook should be ran */

run (?)

+/** An event that may reprisent any event */

Typo

+/** A pacnew file was created */

A .pacnew file ...

+/** A pacsace file was created */

A .pacsave file ...

+/** pre/post transaction hooks are to be ran */

run

+   /** Type of event it's always safe to access this. */

Type of event.  It is always...

+   /** The any event type. It's always safe to access this. */

It is

+   /** An optdept was remove */

optdep ... removed

+   /** A pacnew file was created */

.pacnew

+   /** A pacsave file was created */

.pacsave

+   /** Pre/post transaction hooks are being ran */

Run



+   /** The type of question. It's always safe to access this. */

It is

+   /** A question that can represent any question.
+* It's always safe to access this. */

It is

+   /** Package Integrity checking */

lower case i

+ * @param howmany the total amount of items in the action

total number of


+ * many libalpm will produce log output. Additionally any calls to
\link alpm_logaction

many libalpm  will

+ * @brief Libalpm option getters and setters

getter/accessor - or is that too C++?


+/**Returns the callback used for operation progress.

Space after /**

+ * Hooks and scriptlets will also be run in a chroot to ensure they
behave correctly

in a chroot at this directory

+ * matter if the lockfile is actually presant on disk.

Typo

+/** Gets the currently configured cachedirs,

Inconsistent trailing ,

+ * @param cachedirs a char* list of cachdirs. The list will be duped and

duplicated

+/** Gets the currently configured overwritable files,

Comma

+ * @param globs a char* list of overwritable file globs. The list will
be duped and

Duplicated

+ * @return the path to libalpms's GnuPG home directory

s's

+ * The list will be duped and the original will still need to be freed
by the caller.

duplicated

+ * @return 0 is the path matches a glob, negative if there is no match and
+ * positive is the  match was inverted

double space.   Also "inverted"?

+ * The list will be duped and the original will still need to be freed
by the caller.

duplicated

+ * @return 0 is the path matches a glob, negative if there is no match and
+ * positive is the  match was inverted

As above.

+ * The list will be duped and the original will still need to be freed
by the caller.

duplicated

+ * The list will be duped and the original will still need to be freed
by the caller.

Duplicated

+/** Gets the list of dependencies that are assumed to be met

s/dependencies/packages

+/** Add a depend to the assumed installed list

s/dependencies/packages

+/** Sets the list of dependnecies that are assumed to be met

packages that are assumed to be installed

+/** @name Accessors for check space.

I know this is literally called "CheckSpace", but can we be more

Re: [pacman-dev] [PATCH 2/2] Docs docs docs and more docs

[Allan McRae]

On 26/1/20 5:01 pm, morganamilo wrote:
> Write docs for every public alpm member and expand on the existing
> documentation for other members.
> 
> ---
> 
> The entire .h file has basically been restructed. The best way to see
> the end result is either to read the generated man pages or enabled html
> and view the generated html.
> 
> Also note alpm_list is still not documented.

I have not gone through all the content yet, but here is a few things I
noticed when apply and building docs:

Applying: Docs docs docs and more docs
.git/rebase-apply/patch:220: trailing whitespace.
/** Returns the current error code from the handle.
.git/rebase-apply/patch:683: trailing whitespace.
/** A database is missing
.git/rebase-apply/patch:760: trailing whitespace.
/** Event callback.
.git/rebase-apply/patch:1010: trailing whitespace.
/** Sets the callback used for logging.
.git/rebase-apply/patch:1023: trailing whitespace.
/** Returns the callback used to report download progress.
warning: squelched 2 whitespace errors
warning: 7 lines add whitespace errors.


/home/allan/arch/code/pacman/lib/libalpm/alpm_list.h:40: warning: group
alpm_list: ignoring title "ALPM List" that does not match old title
"List Functions"


/home/allan/arch/code/pacman/lib/libalpm/alpm.h:1128: warning: Found
unknown command '\parama'
/home/allan/arch/code/pacman/lib/libalpm/alpm.h:1597: warning: unable to
resolve link to 'alpm_siglevel_t' for \link command

(not sure if that last one is due to this patch)


Looks like our Doxyfile.in could be updated.  Probably could restrict
the files it makes documentation for if everything is going to alpm.h
and alpm_list.h.

> +/**
> + * @file alpm.h
> + * @author Pacman Development Team
> + * @date 26 Jan 2020
> + * @brief Arch Linux Package Manager Library
> + *
> + * bork
> + */
> +


Can we get rid of the date?  It is like to become outdated with the next
patch...

Also, bork?


Allan

[pacman-dev] [PATCH 2/2] Docs docs docs and more docs

[morganamilo]

Write docs for every public alpm member and expand on the existing
documentation for other members.

---

The entire .h file has basically been restructed. The best way to see
the end result is either to read the generated man pages or enabled html
and view the generated html.

Also note alpm_list is still not documented.
---
 lib/libalpm/alpm.h  | 1546 ++-
 lib/libalpm/alpm_list.h |   14 +-
 lib/libalpm/version.c   |2 +-
 3 files changed, 1200 insertions(+), 362 deletions(-)

diff --git a/lib/libalpm/alpm.h b/lib/libalpm/alpm.h
index 4a2d2fc1..51e9e5b4 100644
--- a/lib/libalpm/alpm.h
+++ b/lib/libalpm/alpm.h
@@ -20,6 +20,16 @@
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see .
  */
+
+/**
+ * @file alpm.h
+ * @author Pacman Development Team
+ * @date 26 Jan 2020
+ * @brief Arch Linux Package Manager Library
+ *
+ * bork
+ */
+
 #ifndef ALPM_H
 #define ALPM_H
 
@@ -38,267 +48,313 @@ extern "C" {
 #include 
 
 /*
- * Arch Linux Package Management library
+ * Opaque Structures
  */
 
-/*
- * Opaque Structures
+/** The libalpm context handle.
+ *
+ * This struct represents an instance of libalpm.
  */
 typedef struct __alpm_handle_t alpm_handle_t;
+
+/** A database.
+ *
+ * A database is a container that stores metadata about packages.
+ *
+ * A database can be located on the local filesystem or on a remote server.
+ *
+ * To use a database, it must first be registered via \link 
alpm_register_syncdb \endlink.
+ * If the database is already preasant in the dbpath then it will be usable. 
Otherwise,
+ * the database needs to be downloaded using \link alpm_db_update \endlink. 
Even if the
+ * source of the database is the local filesystem.
+ *
+ * After this, the database can be used to query packages and groups. Any 
packages or groups
+ * from the database will continue to be owned by the database and do not need 
to be freed by
+ * the user. They will be freed when the database is unregistered.
+ *
+ * Databases are automatically unregistered when the \link alpm_handle_t 
\endlink is released.
+ */
 typedef struct __alpm_db_t alpm_db_t;
+
+/** A package
+ *
+ * A package can be loaded from disk via \link alpm_pkg_load \endlink or 
retrieved from a database.
+ * Packages from databases are automatically freed when the database is 
unregistered. Packages loaded
+ * from a file must be freed manually.
+ *
+ * Packages can then be queried for metadata or added to a \link alpm_trans_t 
transaction \endlink
+ * to be added or removed from the system.
+ */
 typedef struct __alpm_pkg_t alpm_pkg_t;
+
+/** Transaction structure used internally by libalpm */
 typedef struct __alpm_trans_t alpm_trans_t;
 
-/** @addtogroup alpm_api_errors Error Codes
+/** @addtogroup alpm_api ALPM
+ * @brief The libalpm Public API
+ * @{
+ */
+
+/** @addtogroup alpm_errors Error Codes
+ * @brief The error codes used by libalpm
  * @{
  */
+
+/** libalpm's error type */
 typedef enum _alpm_errno_t {
+   /** No error */
ALPM_ERR_OK = 0,
+   /** Failed to allocate memory */
ALPM_ERR_MEMORY,
+   /** A system error occurred */
ALPM_ERR_SYSTEM,
+   /** Permmision denied */
ALPM_ERR_BADPERMS,
+   /** Should be a file */
ALPM_ERR_NOT_A_FILE,
+   /** Should be a directory */
ALPM_ERR_NOT_A_DIR,
+   /** Function was called with invalid arguments */
ALPM_ERR_WRONG_ARGS,
+   /** Insufficient disk space */
ALPM_ERR_DISK_SPACE,
/* Interface */
+   /** Handle should be null */
ALPM_ERR_HANDLE_NULL,
+   /** Handle should not be null */
ALPM_ERR_HANDLE_NOT_NULL,
+   /** Failed to acquire lock */
ALPM_ERR_HANDLE_LOCK,
/* Databases */
+   /** Failed to open database */
ALPM_ERR_DB_OPEN,
+   /** Failed to create database */
ALPM_ERR_DB_CREATE,
+   /** Database should not be null */
ALPM_ERR_DB_NULL,
+   /** Database should be null */
ALPM_ERR_DB_NOT_NULL,
+   /** The database could not be found */
ALPM_ERR_DB_NOT_FOUND,
+   /** Database is invalid */
ALPM_ERR_DB_INVALID,
+   /** Database has an invalid signature */
ALPM_ERR_DB_INVALID_SIG,
+   /** The localdb is in a newer/older format than libalpm expects */
ALPM_ERR_DB_VERSION,
+   /** Fauked to write to the database */
ALPM_ERR_DB_WRITE,
+   /** Fauked to remove entry from database */
ALPM_ERR_DB_REMOVE,
/* Servers */
+   /** Server URL is in an invalid format */
ALPM_ERR_SERVER_BAD_URL,
+   /** The database has no configured servers */
ALPM_ERR_SERVER_NONE,
/* Transactions */
+   /** A transaction is already initialized */
ALPM_ERR_TRANS_NOT_NULL,
+   /** A transaction has not been initialized */
ALPM_ERR_TRANS_NULL,
+   /** Duplicate