-
Notifications
You must be signed in to change notification settings - Fork 24
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: Specification update to clean up and improve documentation for proto message definitions #388
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
jsync-swirlds
changed the title
docs: Documentation Update to clean up and improve documentation for proto message definitions
docs: Specification update to clean up and improve documentation for proto message definitions
Jul 11, 2024
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
6 times, most recently
from
July 19, 2024 00:51
fb4bc88
to
df235a5
Compare
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
4 times, most recently
from
July 24, 2024 23:38
658ad21
to
e4dfc42
Compare
1 task
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
3 times, most recently
from
August 1, 2024 18:02
85a8dc1
to
99947b7
Compare
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
2 times, most recently
from
August 9, 2024 19:33
030315e
to
3c26875
Compare
jsync-swirlds
commented
Aug 9, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
.
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
7 times, most recently
from
August 14, 2024 23:58
22a1201
to
5ffdb1c
Compare
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
2 times, most recently
from
August 22, 2024 21:21
8abac61
to
243d22f
Compare
…message definitions * Added svg diagrams for most state objects. * Clean up copyright headers to remove non-printing characters. * Began reworking documents to produce clear documentation via the most common document processor for protobuf * There are limitations that encourage a slightly different style. * Markdown produces the best output (with slight modifications to the template), so that is selected. * Added a modified markdown template (to work around the "sanitization" bug in the docs processor for markdown). * Now we can add most HTML tags in the markdown, allowing things like line breaks in attribute descriptions. * The results are much better, might be something worth submitting as a PR upstream (along with some non-trivial examples)... * This allows using a line with only `<br/>` or `<p>` in place of blank lines (that break the markdown tables). * Ideally the go code would do this, but that's a bigger lift, this works for now. * Thorough update of many proto files in state. * Committed a fully generated set of docs in this branch for review purposes, will remove before completing the task. * Moved document outputs to `documents/api/services` to allow for other document sets * Removed unused imports to quiet warnings. * Replicate "service" documentation to the message body entries for clarity * Message bodies were just "see ..." references, which do not link well, and push content specification to the service API, which muddies both. * Rewrite message body documentation to *content* specification * Rewrite "service" API documentation to *API* specification. * Adjust common fields to have consistent descriptions. Mass update of the copyright header. * Updated copyright header to match services standard. * Corrected incorrect copy-paste of older years in state. * Removed hidden zero-width characters. * Removed unnecessary additions. * Adjusted query header and query response header text to be more uniform. * Thorough update across services proto definitions * State messages complete * Consensus service complete * Smart Contract service complete. * Crypto Service complete. * Miscellaneous protos complete. * File Service complete. * Freeze Service complete. * Transaction and records complete. * Synthetic node_stake_update transaction complete. * Query and Response complete. * General Queries complete. * Harmonized crypto_get_info and get_account_details * Discovered no service interface defines `getByKey`, we may be able to completely remove that query, with it's handler in network admin service, and just reserve the field number in query and hedera functionality henceforth. * Found a few more unsupported queries and marked them deprecated in the query.proto one-of block. * Network Service complete * Schedule Service complete * Token Service complete * Fixed the new `token_reject` file, which was not created according to the content in the HIP. * Utility Service complete. * Address Book Service complete. * Minor updates and clarification only. * HIP 904 additions * Updated all airdrop and pending airdrop entries. * Response Code * Separate due to size (iover 360 fields) and frequent changes. Will be addressed in a separate PR to minimize conflict with ongoing services work. Signed-off-by: Joseph Sinclair <[email protected]>
* Documentation is moved to the hip-1037-documentation branch Signed-off-by: Joseph Sinclair <[email protected]>
* Fixed incorrect reference in block header. * Improvements to style guidelines file. * Small review fixes. Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
from
December 10, 2024 17:37
763c39a
to
b0f1ea6
Compare
* Many suggestions slightly rewritten to better match style guidelines. * Harmonized use of the `reserved` keyword. * Added several clarifications to style guidelines. * Changed wording for `memo` fields to refer to the system property that governs the length limit * Fixed field ordering in transaction body to work around PBJ limitation. * Adjusted wording and corrected misunderstandings in both File and network admin services. * Fixed inconsistend description for ledger ID. * Clarified what is a "system" file and the requirement that "system" files cannot be deleted. * Deprecated several obsolete and unsupported queries and transactions. * Minor changes to accomodate JavaDoc's broken HTML processing. * Apparently, services insists on generating javadoc for generated code. * Added purpose description for `SignaturePair.pubKeyPrefix` based on a question raised recently, and answers given. Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
force-pushed
the
pbj-storage-spec-review
branch
from
December 10, 2024 17:43
b0f1ea6
to
db889af
Compare
kimbor
approved these changes
Dec 11, 2024
jeromy-cannon
approved these changes
Dec 11, 2024
povolev15
approved these changes
Dec 11, 2024
povolev15
requested review from
derektriley,
thomas-swirlds-labs,
iwsimon,
tinker-michaelj and
rbarkerSL
December 11, 2024 15:53
Neeharika-Sompalli
approved these changes
Dec 11, 2024
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM! Thanks @jsync-swirlds
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 11, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` * Removed references in test clients to obsolete removed functionality * Removed three unused imports. Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 12, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` * Removed references in test clients to obsolete removed functionality * Removed three unused imports. * Removed HAPI tests for unsupported queries that are removed. Signed-off-by: Joseph Sinclair <[email protected]>
jsync-swirlds
added a commit
to hashgraph/hedera-services
that referenced
this pull request
Dec 12, 2024
* Merged all changes from [PR 388](hashgraph/hedera-protobufs#388) in `hedera-protobufs` * Removed references in test clients to obsolete removed functionality * Removed three unused imports. * Removed HAPI tests for unsupported queries that are removed. Signed-off-by: Joseph Sinclair <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Massive update to all services proto files to update and correct in-place
specification and documentation.
common document processor for protobuf
so that is selected.
the docs processor for markdown).
in attribute descriptions.
<br/>
or<p>
in place of blanklines (that break the markdown tables).
purposes.
documents/api/services
to allow for other document setsand push content specification to the service API, which muddies both.
getByKey
, we may be able tocompletely remove that query, with it's handler in network admin service,
and just reserve the field number in query and hedera functionality henceforth.
query.proto one-of block.
token_reject
file, which was not created according tothe content in the HIP.
Will be addressed in a separate PR and HIP to minimize conflict.