Add missing docstrings for EquivalenceLibrary

[raynelfss]

Summary

The following commits attempt to fix #13258 by adding all of the missing docstrings that were lost after #12585.

Details and comments

Add missing docstrings in the following methods:

• Python (PyO3):
  • EquivalenceLibrary struct class.
  • EquivalenceLibrary::get_graph method.
  • EquivalenceLibrary::py_keys method.
  • EquivalenceLibrary::py_node_index method.
• Rust:
  • EquivalenceLibrary::keys method.

[qiskit-bot]

One or more of the following people are relevant to this code:

• @Qiskit/terra-core

[coveralls]

Pull Request Test Coverage Report for Build 11709092718

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 0 of 2 (0.0%) changed or added relevant lines in 1 file are covered.
• 2385 unchanged lines in 129 files lost coverage.
• Overall coverage decreased (-0.1%) to 88.774%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/accelerate/src/equivalence.rs	0	2	0.0%

Files with Coverage Reduction	New Missed Lines	%
qiskit/transpiler/passes/scheduling/alignments/pulse_gate_validation.py	1	96.3%
qiskit/circuit/library/iqp.py	1	96.15%
qiskit/transpiler/passes/calibration/pulse_gate.py	1	95.45%
qiskit/circuit/library/boolean_logic/quantum_or.py	1	98.08%
qiskit/pulse/instructions/reference.py	1	93.55%
qiskit/circuit/library/standard_gates/u.py	1	93.0%
qiskit/circuit/library/boolean_logic/quantum_and.py	1	97.96%
qiskit/synthesis/unitary/qsd.py	1	97.58%
qiskit/pulse/instructions/directives.py	1	97.14%
qiskit/circuit/library/boolean_logic/inner_product.py	1	96.0%

Totals
Change from base Build 11219438971:	-0.1%
Covered Lines:	77108
Relevant Lines:	86859

---

💛 - Coveralls

[kevinhartman]

Is there a reason to go with H2 here?

[raynelfss]

Nothing more than just me thinking H1 looks a bit too big here.

[kevinhartman]

Heh, understandable. Regardless, it looks like the Rust standard library uses H1 for a first level section, but it also looks like documenting arguments separately like we do in Python is actually not hip in Rust.

I would recommend that we just remove the Arguments and Returns sections on all of these methods altogether. To describe arguments that aren't self-explanatory, add a second paragraph after the summary sentence to describe the usage.

Here's what the Rust standard library uses as their convention: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text

[kevinhartman]

The Python docs look good. I left one comment recommending we use lowercase generic terms in cases where we don't want to make a code reference to a type. In general, prefer circuit or :class:`.QuantumCircuit` over QuantumCircuit. This is a fairly standard practice, e.g. Rust gives this guidance in its standard library style guide. The rationale that comes to mind is that if we know the exact type in question, we might as well use a code reference.

As for the Rust docs, I'd recommend we drop all of the Args and Returns sections, and stick with just a summary sentence, followed by an optional paragraph that describes any usage details. It's just not standard practice in Rust to list out arguments like we see in Python docs. Instead, the Rust community favors a cohesive usage description of the function as a whole when arguments aren't obvious, along with an Examples section, ideally for every method to provide usage examples. It's probably alright to skip the Examples section for most of the methods you've got in this PR, since the usage is self-explanatory and this is not yet a public interface.

[mtreinish]

LGTM, thanks for fixing this.