Check that exported symbols have documentation

[stylewarning]

(Same with QVM and MAGICL.)

[stylewarning]

(I think we should make a new system for this.)

[notmgsk]

A new system?

Something like a linter would be cool.

[stylewarning]

See also: https://github.com/rigetti/quilc/issues/40

[jmbr]

I'm still advocating for a Rigetti-specific version of the lisp-critic.

[rigettizach]

I wrote a new program to dig up this kind of info. Here's a report it can produce, with additional remarks added manually in italics.

Many of these are easy fixes. Two exceptions stand out:

• adt:defdata generates new constants and structures, and needs an update to attach documentation to those
• the protocol-less <class>-<slot> accessors need documented protocols, with defgenerics

A final issue to consider: sometimes external symbols are just syntax, and do not have a natural place to hang documentation. Consider it in anaphoric libraries, or otherwise in CL. It would take some extra thought to exclude them from a report on problematic symbols.

The report:

cl-quil

Class

• circuit-definition
• controlled-gate
• dagger-gate
• forked-gate

Compiler-Macro

• inst
• inst*

Constant

These are self-evident, to me, but a missing docstring is a missing docstring.

• 2pi
• 4pi
• -pi
• pi/2
• -pi/2

These arise from adt:defdata.

• quil-bit
• quil-integer
• quil-octet
• quil-real

Function

• build-8q-chip
• comment
• controlled-operator
• dagger-operator
• make-pragma
• memory-ref=
• named-operator
• print-operator-description
• quil-memory-model-error
• resolve-safely

Macro

• with-output-to-quil

Method

These generally arise from class-slot style of working with classes, rather than protocol-oriented style.

• application-arguments
• application-operator
• application-parameters
• circuit-definition-arguments
• circuit-definition-body
• circuit-definition-name
• circuit-definition-parameters
• classical-left-operand
• classical-left-operand
• classical-right-operand
• classical-right-operand
• classical-target
• classical-target
• classical-target
• conditional-jump-address
• dynamic-gate-arity
• dynamic-gate-arity
• gate-definition-entries
• gate-definition-entries
• gate-definition-name
• gate-definition-parameters
• gate-name
• include-pathname
• jump-label
• jump-target-label
• lexical-context
• lexical-context
• lexical-context
• lexical-context
• measure-address
• measurement-qubit
• not-protoquil-index
• not-protoquil-program
• parameterized-gate-matrix-function
• parsed-program-circuit-definitions
• parsed-program-executable-code
• parsed-program-gate-definitions
• parsed-program-memory-definitions
• permutation-gate-definition-permutation
• permutation-gate-permutation
• pragma-freeform-string
• pragma-matrix-entries
• pragma-matrix-entries
• pragma-operator-name
• pragma-qubit-arguments
• pragma-qubit-index
• pragma-words
• reset-qubit-target
• simple-gate-matrix
• target
• target
• target
• unsatisfied-transform-dependency-attempted-transform
• unsatisfied-transform-dependency-needed-transform
• unsatisfied-transform-dependency-object

Structure

These are all due to adt:defdata.

• controlled-operator
• dagger-operator
• named-operator
• quil-bit
• quil-integer
• quil-octet
• quil-real

Type

• lexical-context
• token-type

  cl-quil.resource

Undefined external symbols

• build-qubit-pair-resource

Function

• make-all-resource
• make-null-resource
• make-qubit-resource

  cl-quil.clifford

Undefined external symbols

• apply-clifford-string
• clifford-element-string

Constant

• +i+
• +x+
• +y+
• +z+

Function

• clifford-identity-p

Generic-Function

• num-qubits

Method

• gateset
• num-qubits
• num-qubits
• num-qubits
• num-qubits
• reconstruct

Structure

• pauli

[stylewarning]

@rigettizach Cool!