-/* compute the alias and store at aliasp. Returns 0 or DB_LOCK_DEADLOCK. If
- * there is no alias sets *aliasp to 0. */
+/** @brief Compute an alias
+ * @param aliasp Where to put alias (gets NULL if none)
+ * @param track Track to find alias for
+ * @param p Prefs for @p track
+ * @param tid Owning transaction
+ * @return 0 or DB_LOCK_DEADLOCK
+ *
+ * This function looks up the track name parts for @p track. By default these
+ * amount to the original values from the track name but are overridden by
+ * preferences.
+ *
+ * These values are then substituted into the pattern defined by the @b alias
+ * command; see disorder_config(5) for the syntax.
+ *
+ * The track is only considered to have an alias if all of the following are
+ * true:
+ * - a preference was used for at least one name part
+ * - the result differs from the original track name
+ * - the result does not match any existing track or alias
+ */