Suggest constructor arguments of generated classes

[ehennestad]

Motivation

Problem — A user who creates an NWB object by typing a constructor such as types.core.ElectricalSeries( gets no suggestions for its arguments, and has to look up the property names in the documentation or the class file. MATLAB suggests name-value arguments only for functions listed in a functionSignatures.json file in the resources folder next to +types. MatNWB's file lists its own functions, such as nwbRead and generateCore, but none of the 96 generated classes. The generated constructors take varargin, so MATLAB has nothing else to suggest from.

Solution — Generating classes now also writes a signature entry for each constructor, listing the properties it can set with the description from the schema. MATLAB suggests these names while the user types the constructor call. The entries are rebuilt whenever classes are generated, copied from the cache (#926) or cleared, so they always match the classes on the path.

What changed

• After generateCore, generateExtension, nwbInstallExtension or nwbRead, MATLAB suggests the name-value arguments of every generated constructor, with the schema description of each.
• The suggestions include properties inherited from superclasses. Read-only properties are left out, and so are properties that hold a set of typed members (for example the nwbdatainterface set of ProcessingModule), because those members are passed under their own names.
• The committed resources/functionSignatures.json lists the committed classes (core 2.11.0, hdmf-common 1.10.0, hdmf-experimental 0.6.0), so suggestions work in a fresh clone without generating anything.
• nwbClearGenerated removes the entries of the classes it deletes.
• Generating another schema version changes resources/functionSignatures.json, as it changes the files in +types.
• The hand-written signatures of MatNWB functions move to resources/function_templates/functionSignatures.json. Edits to them go there; resources/functionSignatures.json is rebuilt from that file.

Implementation notes

• file.fillFunctionSignature creates one entry per class from the same merged property list that file.fillConstructor uses for the help text. The set properties it leaves out are the ones for which the constructor uses types.untyped.Set() as the default.
• file.writeNamespace writes the entries of a namespace to +types/+<namespace>/functionSignatures.fragment.json. The fragment is part of the namespace folder, so the cache from Reuse generated classes from a cache in nwbRead and generateCore #926 stores and restores it with the classes.
• matnwb.internal.typecache.writeFunctionSignatures(saveDir) rebuilds saveDir/resources/functionSignatures.json from the fragments, and adds the hand-written entries when saveDir is the MatNWB root. It combines the files as text, because the hand-written file repeats the key generateCore to declare two signatures, which jsondecode does not keep.
• MATLAB reads the file only from the resources folder next to the outermost namespace folder, so with a custom savedir the file is written to <savedir>/resources.

Examples

Constructor entries in the signatures file

The snippet counts the constructor entries in the signatures file of the MatNWB root folder and checks for types.core.TimeSeries.

signatureText = fileread(fullfile("resources", "functionSignatures.json"));
fprintf("constructor entries: %d\n", count(signatureText, """types."))
fprintf("TimeSeries entry present: %d\n", contains(signatureText, """types.core.TimeSeries"""))

Before — The file lists only MatNWB functions, so MATLAB has no suggestions for generated constructors.

constructor entries: 0
TimeSeries entry present: 0

After — Every generated class has an entry: 83 in core, 12 in hdmf-common and 1 in hdmf-experimental.

constructor entries: 96
TimeSeries entry present: 1

An entry lists each argument with the schema description that MATLAB shows next to the suggestion. The start of the entry for ElectricalSeries:

"types.core.ElectricalSeries": {
  "inputs": [
    {
      "name": "channel_conversion",
      "kind": "namevalue",
      "purpose": "Channel-specific conversion factor. Multiply the data in the 'data' dataset by these values along the channel axis ..."
    },
    {
      "name": "comments",
      "kind": "namevalue",
      ...

How to test

In a fresh MATLAB session with MatNWB on the path, type types.core.ElectricalSeries( in the editor or the Command Window and press Tab: MATLAB lists the property names. Then run the tests, which check the entries for a small test schema, the file after a cache copy, and the file after nwbClearGenerated:

results = runtests("tests.unit.TypeCacheTest");
disp(table(results))

Checklist

• Have you ensured the PR description clearly describes the problem and solutions?
• Have you checked to ensure that there aren't other open or previously closed Pull Requests for the same change?
• If this PR fixes an issue, is the first line of the PR description fix #XX where XX is the issue number?

🤖 Generated with Claude Code