opensource/iot-dc3
3
0
Fork 0
mirror of https://gitee.com/pnoker/iot-dc3.git synced 2026-09-18 00:32:57 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(comments): fill the real comment gaps across the repository

Browse Source 
A comment-health audit driven by an AST scanner (regex scanners kept
false-positiving on annotation-separated javadoc; the AST pass with
constructor and @Override-implementation exemptions is what produced a
trustworthy worklist) ended with a much smaller true gap than the raw
numbers suggested: class-level javadoc is already at 100% repository-wide.

What actually gets filled here:

- AnalyticsModel: all 30 nested records of the S19 analytics facet get
  maintainer-voice javadoc (the @Schema descriptions serve the API side;
  these serve code readers).
- The whole entity/ext family (29 files, 47 nested classes): every
  Content/Ui/Validation/Security/AppliesTo/Template/Dedup/... schema
  class states what it actually holds — read from the fields, not
  templated.
- Adapter families: the @Bean methods of all six MQ adapters, all four
  TSDB adapters and the three DB dialect adapters get one-line
  maintainer docs (what binds to what, what is overridable).
- Nested support types across data/agentic/constant/public/facade:
  NotifyBindKey, CacheTuning, Credential, dashboard VOs' Item/BucketVO,
  ExpireListener (plus its null-doc placeholder javadoc replaced with a
  real contract), agentic chat/stream VOs' choice/delta/usage shapes,
  tool-context records, RequestHeader envelopes, FleetSummary,
  visualization Type/Scale codes.
- PointValueSampleConverter's boundary methods now state the port-side
  contract (quality default injection point, batch order preservation).

Comment drift fixed: the class javadoc of the can/mqtt/opc-da driver
skeletons claimed "see TODO markers in method bodies" — those markers
do not exist; the claims are corrected to plain work-in-progress notes.
The genuine TODOs (zigbee API verification, lwm2m lookup, ethernet-ip
CIP framing, CAN JNI) stay: they mark real unimplemented behavior.

Vendored-code boundary: the opc-da module carries a ported
org.openscada library (46 files, package org.openscada.*). Its trivial
accessors stay bare on purpose — filler comments on get/set pairs are
exactly the kind of noise this pass exists to remove — but the
non-obvious JIStruct wire-decoder methods (getStruct/fromStruct
FILETIME + three DO wrappers) now document the COM bridge shape.

Gates: full-repo compile green; data/model/constant/agentic/public
test suites green.
This commit is contained in:
pnoker
2026-08-24 21:23:39 +08:00
parent 4371650a6e
commit 1fa2d6f0cf
107 changed files with 519 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dc3/doc/README.md
+2 -1
View File
@@ -14,7 +14,8 @@
|-------------------------------|------------------------------------------------------------------------------------|
| [`TITLE.md`](./TITLE.md) | Release title and summary, assembled into the GitHub Release body by `.github/workflows/docker-ci.yml` |
| [`CHANGE.md`](./CHANGE.md) | Version changelog, written by `dc3/bin/changelog.py` and assembled into the Release body by docker-ci |
| [`USAGE.md`](./USAGE.md) | Image usage guide, assembled into the Release body by docker-ci |
| [`RELEASE-FOOTER.md`](./RELEASE-FOOTER.md) | Release quick-start footer (docs links and image pinning), assembled into the Release body by docker-ci |
| [`USAGE.md`](./USAGE.md) | Image usage guide; embedded into the docs site usage page and referenced from the release footer |
| [`DEPLOYMENT.md`](./DEPLOYMENT.md) | Full deployment runbook (compose scale / swarm / k8s / helm); linked from `USAGE.md` and snapshotted into the docs site by `scripts/sync-external.sh` in the docs repository |
The documentation site embeds the [changelog](https://docs.dc3.site/en/development/changelog)