Skip to content

Standardize core schema documentation style#704

Merged
rly merged 19 commits into
devfrom
codex/fix-core-schema-doc-style
Jul 3, 2026
Merged

Standardize core schema documentation style#704
rly merged 19 commits into
devfrom
codex/fix-core-schema-doc-style

Conversation

@ehennestad

@ehennestad ehennestad commented Jun 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

NB: This PR is stacked on #695 and should be reviewed after that PR.

Summary of changes

  • Standardize dimensionality notation as 1-D, 2-D, and 3-D.
  • Standardize e.g., and i.e., punctuation throughout the core schema documentation.
  • Correct the Subject.sex description to refer to biological sex rather than gender.
  • Correct grammar, identifier terminology, and unit wording without changing schema contracts.

Checklist

For all schema changes:

  • Add release notes for the PR to docs/format/source/format_release_notes.rst.
  • Have you included the relevant issue number using "Fix #XXX" notation where XXX is the issue number? Not applicable: no issue is being closed by these style corrections.
  • Make sure that hdmf-common-schema points to the latest release and not the latest commit on the main branch.

ehennestad and others added 3 commits June 28, 2026 07:57
@ehennestad @claude
Fix copy-paste doc errors in icephys, image, misc, and ophys schemas
13727e4 
- nwb.icephys.yaml: VoltageClampSeries.capacitance_slow unit attribute doc
  incorrectly referenced 'capacitance_fast'; corrected to 'capacitance_slow'
- nwb.misc.yaml: IntervalSeries.data resolution and unit attribute docs were
  verbatim copy-paste from AnnotationSeries ("Annotations have no units…");
  updated to accurately describe IntervalSeries integer marker semantics
- nwb.image.yaml: IndexSeries.indexed_images link doc referenced the
  non-existent dataset name 'ordered_images'; corrected to 'order_of_images'
  to match the actual field defined in nwb.base.yaml
- nwb.ophys.yaml: ImagingPlane.device link doc said "record from this
  electrode", which is domain-incorrect for an optical physiology type;
  updated to reference imaging/microscope usage

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Bump version to 2.10.1-alpha and add release notes
b3badee 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad
Update nwb.ophys.yaml
93c005a
@ehennestad
ehennestad force-pushed the codex/fix-core-schema-doc-style branch from d24593f to 9bf38f5 Compare June 28, 2026 12:44
ehennestad and others added 3 commits June 28, 2026 14:48
@ehennestad @claude
Fix doc errors in nwb.ophys: ROITable and e.g. comma
40a83e9 
- RoiResponseSeries.rois: replace non-existent type 'ROITable' with
  'PlaneSegmentation'; fix 'timeseries' capitalisation to 'TimeSeries'
- ImagingPlane.device: add missing comma after 'e.g.'

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad
docs: standardize core schema prose
2d0e1b3
@ehennestad
docs: distinguish sex from gender
1ba8620
@ehennestad
ehennestad force-pushed the codex/fix-core-schema-doc-style branch from 9bf38f5 to 1ba8620 Compare June 28, 2026 12:49
ehennestad and others added 9 commits June 28, 2026 15:02
@ehennestad @claude
Fix typos and misspellings in core schema doc strings
67ad2fa 
- nwb.file.yaml: stimuluation -> stimulation; as as -> as; the a sequence
  -> a sequence; experimental experimental_conditions -> experimental
  conditions; experiment`s -> experiment's (backtick used as apostrophe)
- nwb.ecephys.yaml: zero- filled -> zero-filled (erroneous space in hyphenated compound)
- nwb.retinotopy.yaml: stray leading quote before ['radius', 'theta'] example

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Standardise DEPRECATED tag formatting to include trailing period
8d48c1a 
All other DEPRECATED tags in the schema use 'DEPRECATED.' with a period
before the sentence that follows. Fix the three inconsistent instances in
nwb.ecephys.yaml (ClusterWaveforms, Clustering) and nwb.ophys.yaml
(ImagingPlane.manifold).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Fix i.e. punctuation and missing terminal periods in core schema docs
9d7e620 
- nwb.ecephys.yaml: two instances of 'i.e,' corrected to 'i.e.,';
  missing terminal periods on ClusterWaveforms.waveform_mean,
  waveform_sd, and clustering_interface link doc
- nwb.icephys.yaml: missing terminal periods on
  IZeroClampSeries.stimulus_description and
  IntracellularResponsesTable.response
- nwb.retinotopy.yaml: missing terminal period on
  vasculature_image.bits_per_pixel

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Replace informal language with formal prose in core schema docs
c2c0f07 
- nwb.ophys.yaml: 'w/' -> 'with'; 'x & y' -> 'x and y'
- nwb.retinotopy.yaml: 'Right now only' -> 'Currently only' (x2)
- nwb.image.yaml: contraction 'it's' -> 'it is'
- nwb.ecephys.yaml: contraction 'it's' -> 'it is'

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Fix grammar errors — missing words, wrong words, and double spaces
f1fa362 
- nwb.file.yaml: 'than' -> 'that' (Place-holder); 'these be used' ->
  'these can be used'; 'after experiment complete' -> 'after the
  experiment is complete'; 'to common timebase' -> 'to a common
  timebase'; fix comma placement after 'both'; 'etc,' -> 'etc.'
- nwb.icephys.yaml: 'allows to group' -> 'allows users to group';
  remove double space after 'e.g.,'
- nwb.behavior.yaml: 'take the output one specific' -> 'output of one
  specific'; 'is published' -> 'are published' (plural subject);
  'si_unit' -> 'unit' (field does not exist); 'axis' -> 'axes';
  remove double space after sentence-ending period

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Fix subject-verb agreement and missing articles in core schema docs
656693e 
- nwb.ophys.yaml: 'larger numbers in x/y/z means' -> 'mean' (plural
  subject; three instances in ImagingPlane.reference_frame)
- nwb.misc.yaml: 'for visual grating stimulus' -> 'for a visual grating
  stimulus' (missing article)
- nwb.retinotopy.yaml: 'taken with same settings' -> 'taken with the
  same settings' (missing article)
- nwb.image.yaml: 'must contain a order_of_images' -> 'an' (article
  before vowel-initial quoted word)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
docs: add release notes entry for grammar and style fixes
8157ff5 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Fix invalid YAML in nwb.file.yaml templates doc string
1df514d 
Replacing the backtick with an apostrophe in the previous commit left an
unescaped single quote inside a single-quoted YAML scalar. Remove the
outer single quotes — the string contains no characters that require
quoting.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad @claude
Fix '1::1' typo to '1:1' in FilteredEphys doc string
79a8442 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@ehennestad
ehennestad force-pushed the codex/fix-core-schema-doc-style branch from f27eb3d to 79a8442 Compare June 28, 2026 14:38
@ehennestad @claude
Fix/improve misc doc strings
a070734 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@oruebel

oruebel commented Jun 29, 2026

Copy link
Copy Markdown
Contributor

Overall the current changes look good to me. Could you add an entry to the changelog.

@ehennestad

ehennestad commented Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Overall the current changes look good to me. Could you add an entry to the changelog.

Yes! How precise should I be? One sentence summary or points like the PR summary above?

oruebel
oruebel reviewed Jun 30, 2026
View reviewed changes
Comment thread docs/format/source/format_release_notes.rst Outdated
Base automatically changed from fix/doc-copy-paste-errors to dev June 30, 2026 19:21
@oruebel

oruebel commented Jun 30, 2026

Copy link
Copy Markdown
Contributor

Yes! How precise should I be? One sentence summary or points like the PR summary above?

The entry you added looks good. Just suggest adding the PR number for reference.

@ehennestad
ehennestad marked this pull request as ready for review June 30, 2026 20:32
@ehennestad

ehennestad commented Jul 3, 2026

Copy link
Copy Markdown
Contributor Author

Yes! How precise should I be? One sentence summary or points like the PR summary above?

The entry you added looks good. Just suggest adding the PR number for reference.

Done!

@rly

rly commented Jul 3, 2026

Copy link
Copy Markdown
Contributor

I simplified the release notes entry because I don't think all of the examples are important to list here. Otherwise looks good to me. Thanks @ehennestad !

@rly
rly merged commit db9e52a into dev Jul 3, 2026
6 checks passed
@rly
rly deleted the codex/fix-core-schema-doc-style branch July 3, 2026 19:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@oruebel oruebel oruebel left review comments
@rly rly rly approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@ehennestad @oruebel @rly