[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 <what> 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
descriptive?

+ * This controls whether libalpm will check if there is sufficient before

sufficient what?

+ * This is useful for file databases. Seems as files can increase the
size of

As file lists can ...

+/** Unregister all package databases. Databases can not be
+ * registered while there is an active transaction.

unregistered

+/** Unregister a package database. Databases can not be
+ * registered while there is an active transaction.

unregistered


+	/** Enable search for this database */

Enable search operations for

+	/** Amount of files in the array */

Number of

+	/** Ability to download */
 	ALPM_CAPABILITY_DOWNLOADER = (1 << 1),

Internal downloader


--- a/lib/libalpm/alpm_list.h
+++ b/lib/libalpm/alpm_list.h
@@ -17,6 +17,13 @@
  *  You should have received a copy of the GNU General Public License
  *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+
+/**
+ * @file alpm_list.h
+ * @author Pacman Development Team
+ * @date 26 Jan 2020

Again - I think the date should be removed.