Skip to content

style: use plain comments for in-body implementation notes - #45

Open
mfw78 wants to merge 1 commit into
docs/monitoring-service-deploymentsfrom
style/in-body-comments
Open

style: use plain comments for in-body implementation notes#45
mfw78 wants to merge 1 commit into
docs/monitoring-service-deploymentsfrom
style/in-body-comments

Conversation

@mfw78

@mfw78 mfw78 commented Jul 30, 2026

Copy link
Copy Markdown

solc only recognises NatSpec on declarations, so a @dev tag inside a function body is inert: it documents nothing and no tooling reads it. This demotes the 25 remaining cases to ordinary comments and drops the tag, so that a doc comment in the tree always means NatSpec.

  • single-line notes become //
  • multi-line notes become a plain /* */ block rather than a /** */ doc block

This is the companion to #42, which deliberately left in-body comments alone: expanding a one-line note inside a function body into a three-line doc block would have made the code harder to read, not easier.

This PR is separable. It sits at the tip and nothing below it depends on it, so it can be closed without affecting the rest of the train if you would rather leave in-body comments as they are.

How to test

forge build && forge test

Green (154 passing). The change touches only comments.

Part of #1.

@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from ea5d427 to d822b7d Compare July 30, 2026 04:01
@mfw78
mfw78 force-pushed the style/in-body-comments branch from f23ee93 to bdd0dc7 Compare July 30, 2026 04:01
@mfw78
mfw78 marked this pull request as ready for review July 30, 2026 06:52
@mfw78
mfw78 force-pushed the style/in-body-comments branch from bdd0dc7 to 3b1a01a Compare July 30, 2026 06:59
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from d822b7d to 1befa00 Compare July 30, 2026 06:59
@mfw78
mfw78 force-pushed the style/in-body-comments branch 2 times, most recently from 6979147 to 81fd938 Compare July 30, 2026 07:07
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 1043cdd to 0104481 Compare July 30, 2026 07:07
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 81fd938 to f1e3591 Compare July 30, 2026 07:09
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 83539c7 to 9c72493 Compare July 30, 2026 07:14
@mfw78
mfw78 force-pushed the style/in-body-comments branch from f1e3591 to 968943e Compare July 30, 2026 07:14
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 9c72493 to 99bfe4a Compare July 30, 2026 07:18
@mfw78
mfw78 force-pushed the style/in-body-comments branch 2 times, most recently from 1ef8c09 to 209a7fa Compare July 30, 2026 07:22
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch 2 times, most recently from 2c7570f to 47bf1e7 Compare July 30, 2026 07:26
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 209a7fa to 34abd08 Compare July 30, 2026 07:26
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 47bf1e7 to a1f8a8a Compare July 30, 2026 07:33
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 34abd08 to 7bdae74 Compare July 30, 2026 07:33
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from a1f8a8a to e343718 Compare July 30, 2026 08:23
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 7bdae74 to b569442 Compare July 30, 2026 08:23
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from e343718 to 7a5a798 Compare July 30, 2026 08:42
@mfw78
mfw78 force-pushed the style/in-body-comments branch 2 times, most recently from 7229256 to fe5f94f Compare July 30, 2026 09:51
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 7a5a798 to a060d1c Compare July 30, 2026 09:51
@mfw78
mfw78 force-pushed the style/in-body-comments branch from fe5f94f to 8182be8 Compare July 30, 2026 09:54
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from a060d1c to 09f41a3 Compare July 30, 2026 09:54
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 8182be8 to fe2cdf4 Compare July 30, 2026 10:24
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 4ea86b7 to 7a4d81a Compare July 30, 2026 10:40
@mfw78
mfw78 force-pushed the style/in-body-comments branch from fe2cdf4 to 34795a3 Compare July 30, 2026 10:40
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 9f41967 to f13c656 Compare July 30, 2026 13:55
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 47f2219 to 7a7e6cf Compare July 30, 2026 13:55
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from f13c656 to deee630 Compare July 30, 2026 14:25
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 7a7e6cf to 2034f3a Compare July 30, 2026 14:25
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from deee630 to 84cb438 Compare July 30, 2026 23:43
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 2034f3a to 72fdc2b Compare July 30, 2026 23:43
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 84cb438 to 933737d Compare July 30, 2026 23:51
@mfw78
mfw78 force-pushed the style/in-body-comments branch 3 times, most recently from 49bcb00 to c312d8d Compare July 31, 2026 00:12
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 140abeb to 49c05c3 Compare July 31, 2026 00:12
@mfw78
mfw78 force-pushed the style/in-body-comments branch from c312d8d to de716d6 Compare July 31, 2026 00:14
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch 2 times, most recently from a2b4d6d to 3e2f141 Compare July 31, 2026 04:00
@mfw78
mfw78 force-pushed the style/in-body-comments branch from de716d6 to 0267b62 Compare July 31, 2026 04:00
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 3e2f141 to 58308d7 Compare July 31, 2026 05:26
@mfw78
mfw78 force-pushed the style/in-body-comments branch 2 times, most recently from 001c0a5 to 469fe25 Compare July 31, 2026 06:10
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 58308d7 to 18e270e Compare July 31, 2026 06:10
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 469fe25 to f7b6d6e Compare July 31, 2026 06:14
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 3f530a5 to 1a881b4 Compare July 31, 2026 06:29
@mfw78
mfw78 force-pushed the style/in-body-comments branch from f7b6d6e to 129e08d Compare July 31, 2026 06:29
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 1a881b4 to fb563a6 Compare July 31, 2026 06:31
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 129e08d to 1580f39 Compare July 31, 2026 06:31
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from fb563a6 to 3b1cd6a Compare July 31, 2026 06:42
@mfw78
mfw78 force-pushed the style/in-body-comments branch from 1580f39 to cbad447 Compare July 31, 2026 06:42
@github-actions

Copy link
Copy Markdown


Thank you for your submission, we really appreciate it. Like many open-source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution. You can sign the CLA by just posting a Pull Request Comment same as the below format.


I have read the CLA Document and I hereby sign the CLA


You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.

solc only recognises NatSpec on declarations, so a `@dev` tag inside a function
body is inert: it documents nothing and no tooling reads it. Demote those to
ordinary `//` and `/* */` comments and drop the tag, so that a doc comment in
the tree always means NatSpec.

This is the companion to the NatSpec standardisation earlier in the stack,
which deliberately left in-body comments alone. It is separable from the rest
of the train and can be dropped without affecting anything below it.
@mfw78
mfw78 force-pushed the docs/monitoring-service-deployments branch from 3b1cd6a to 5ce21b9 Compare July 31, 2026 06:54
@mfw78
mfw78 force-pushed the style/in-body-comments branch from cbad447 to 29caf59 Compare July 31, 2026 06:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant