Tagref

Tagref helps manage cross reference in the code.

Example:

def polynomial(x):
    return x ** 2 + 1

def inverse_polynomial(x):
    return 1 / polynomial(x) # This is safe due to [ref:polynomial_nonzero].

Then when running tagref check it complains:

tagref check
## No tag found for [ref:polynomial_nonzero] @ ./temp.py:5.

We can add that tag:

# [tag:polynomial_nonzero] This function never returns zero.
def polynomial(x):
    return x ** 2 + 1

def inverse_polynomial(x):
    return 1 / polynomial(x) # This is safe due to [ref:polynomial_nonzero].

and when running tagref check again it won’t fail because the reference exists.

This tool is excellent for helping maintain a codebase up to date.

My usage

While coding a DNS resolver based on the RFC 1035 I used this. Instead of referring to the RFC using a URL I committed a copy of the RFC in the repository. Then I had things such as:

(defn generate-random-query-id
  "Generate a random 16-bit ID for a DNS query.
   For more info see [ref:header-id]."
  []
  (rand-int (Math/pow 2 16)))

On the RFC I added a tag where it describe the ID:

ID              [tag:header-id]
                A 16 bit identifier assigned by the program that
                generates any kind of query.  This identifier is copied
                the corresponding reply and can be used by the requester
                to match up replies to outstanding queries.

When running tagref is checks all those things:

6 tags, 6 tag references, 0 file references, and 0 directory references validated in 9 files.