api-quality-checks

name	api-quality-checks
description	API class validation rules for Scopy plugins. Auto-loads when reviewing or editing `*_api.h` / `*_api.cpp` files or running API quality checks.

API Quality Check Rules

Apply these 7 validation categories when reviewing or generating API classes for Scopy plugins.

---

CRITICAL

[A1] Inheritance & Structure

• Class inherits from ApiObject
• Q_OBJECT macro is present in the class body
• Export macro (SCOPY_<PLUGIN>_EXPORT) is on the class declaration
• Constructor takes <Plugin>Plugin * as its sole argument

[A2] Plugin Integration

• friend class <Plugin>_API is declared in the plugin header
• m_api is declared as <Plugin>_API *m_api = nullptr; in the plugin header
• initApi() is declared in the plugin header
• initApi() is the last call in onConnect() before return true
• delete m_api; m_api = nullptr; is the first statement in onDisconnect()
• ScopyJS::GetInstance()->registerApi(m_api) is called inside initApi()
• m_api->setObjectName("<name>") uses a lowercase, short name consistent with similar plugins
• The .cpp file ends with #include "moc_<plugin>_api.cpp"

[A3] Null Safety

• Every Q_INVOKABLE method null-checks plugin/instrument members before accessing them
• readFromWidget() / writeToWidget() null-check m_widgetGroup before use

[A5] Conversion Correctness

Cross-reference the tool's IIOWidget lambdas to verify:

• Hz attributes: getter divides raw value ÷1e6; setter multiplies by ×1e6
• Suffix attributes (e.g. " dB"): getter strips the suffix before returning
• dBFS↔linear: getter applies 20*log10(1/linear) rounded to int; setter applies pow(10, -val/20)
• Combo attributes: setter validates the input against a static QStringList before calling writeToWidget

---

WARNING

[A4] API Coverage

• getTools() method is present
• Every writable IIOWidget has a getter and a setter; every read-only widget has only a getter
• Generic readWidget() / writeWidget() helpers are present

[A6] Private Helper Pattern

• readFromWidget(const QString &key) and writeToWidget(const QString &key, const QString &value) are declared as private helpers
• Both helpers null-check m_plugin->m_widgetGroup before accessing it

---

INFO

[A7] Naming & Types

• Getters return QString; setter parameters use const QString &
• No public getters were added to instrument classes just for API access — use friend class instead
• Naming follows the convention: get<Attribute>() / set<Attribute>()