Skip to content

Add descriptive documentation to compose schema properties #581

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.

Sign up for GitHub

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

Jump to bottom
Closed
wants to merge 2 commits into from
Closed

Add descriptive documentation to compose schema properties #581

wants to merge 2 commits into from

Conversation

testA113
Copy link

@testA113 testA113 commented Mar 19, 2025 •
edited
Loading

Improved schema documentation by adding descriptive text to various properties in the JSON schema.

This enhances DX by providing clear explanations of what each property does without requiring users to constantly refer to external documentation.

These changes address issue #138.

The descriptions come from sane descriptions found in https://github.com/microsoft/compose-language-service/blob/7a74283ddb866988fed86241f461a657f0aee6d0/src/service/providers/KeyHoverProvider.ts#L63-L184

@testA113
Add descriptive documentation to compose schema properties
9cc2d23 
Improved schema documentation by adding descriptive text to various properties in the JSON schema. This enhances usability for developers by providing clear explanations of what each property does.

Signed-off-by: testA113 <aliharriss1995@gmail.com>
ndeloof
ndeloof approved these changes Mar 27, 2025
View reviewed changes
Copy link
Collaborator

@ndeloof ndeloof left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, could be later improved

ndeloof
ndeloof requested changes Mar 27, 2025
View reviewed changes
Copy link
Collaborator

@ndeloof ndeloof left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

version attribute must be documented as legacy, deprecated

@testA113
address review comment
57efccc 
Signed-off-by: testA113 <aliharriss1995@gmail.com>
@testA113 testA113 force-pushed the feature/add-schema-descriptions branch from 05231d7 to 57efccc Compare April 7, 2025 23:46
@testA113
Copy link
Author

testA113 commented Apr 7, 2025

Thankyou for the review @ndeloof! Let me know if you need any other changes

@ndeloof ndeloof requested a review from glours April 8, 2025 07:30
@glours
Copy link
Contributor

glours commented Apr 23, 2025

This PR should be done in the https://github.com/compose-spec/compose-go repository, no?
The version of the compose-spec.json file in this repo is just a copy of the compose-go one

@rcjsuen
Copy link

rcjsuen commented Apr 23, 2025

This PR should be done in the https://github.com/compose-spec/compose-go repository, no? The version of the compose-spec.json file in this repo is just a copy of the compose-go one

compose-spec/Makefile

Lines 22 to 24 in d9b3470

.PHONY: sync-spec
sync-spec:
curl -L https://raw.githubusercontent.com/compose-spec/compose-go/refs/heads/main/schema/compose-spec.json -o schema/compose-spec.json

If that is the case then we should add a README.md in the schema folder to educate users about this. I don't think this is clear to people looking at this repository unless they start looking at the code.

@testA113 testA113 mentioned this pull request Apr 27, 2025
Merged
@testA113
Copy link
Author

Improved schema documentation by adding descriptive text to various properties in the JSON schema.

This enhances DX by providing clear explanations of what each property does without requiring users to constantly refer to external documentation.

These changes address issue #138.

The descriptions come from sane descriptions found in https://github.com/microsoft/compose-language-service/blob/7a74283ddb866988fed86241f461a657f0aee6d0/src/service/providers/KeyHoverProvider.ts#L63-L184

Thanks for taking a look @glours! I've applied the same changes in the PR for the compose-go repo you mentioned here. I'll close this PR and let's continue the review there

@testA113 testA113 closed this Apr 27, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ndeloof ndeloof ndeloof approved these changes

@glours glours Awaiting requested review from glours

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@testA113 @glours @rcjsuen @ndeloof