★ wanayoo — archive 1999 https://github.com/PowerShell/PowerShell/pull/7832Nouvelle recherche | Portail wanayoo
Skip to content

/PowerShell

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

Add XSDs for Format and Types.ps1xml files #7832

Merged
merged 1 commit into from Oct 2, 2018
+925 −0

Conversation

Reviewers

@SteveL-MSFT SteveL-MSFT

@adityapatwardhan adityapatwardhan

Assignees

@adityapatwardhan adityapatwardhan

Labels
None yet
Projects
None yet
Milestone
No milestone
4 participants
@felixfbecker @SteveL-MSFT @lzybkr @adityapatwardhan
@felixfbecker
Copy link
Contributor

commented Sep 20, 2018

PR Summary

As proposed in #7749.

These can be used for autocompletion and validation in editors like VS Code. It makes writing Format and Types files so much more pleasant to write.

autocompletion

The schemas were taken from #7749 but extended with documentation parsed from the reference docs markdown with a script.

Question: Should this be hosted on http://schemas.microsoft.com/ like the MAML schemas? How do the MAML schemas get published there?

cc @lzybkr @SteveL-MSFT

PR Checklist
@SteveL-MSFT

SteveL-MSFT requested changes Sep 20, 2018
View changes

Copy link
Member

left a comment

Great contribution! Didn't review the schema itself in detail, but overall it looks fine. We can address as bugs if issues are reported.
src/Schemas/Format.xsd Outdated
</xs:element>
<xs:element minOccurs="0" name="SelectionSets" maxOccurs="1" type="SelectionSets">
<xs:annotation>
<xs:documentation>Optional element. Defines the common sets of .NET Framework objects that can be used by all views of the formatting file.</xs:documentation>

This comment has been minimized.

Sign in to view
Copy link
@SteveL-MSFT

SteveL-MSFT Sep 20, 2018

Member

.NET Framework is specifically not .NET Core. Since this applies to both, I would suggest just changing all occurrences of .NET Framework to simply .NET
Show resolved Hide resolved src/Schemas/Format.xsd
@felixfbecker

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

commented Sep 20, 2018

@SteveL-MSFT as mentioned, all documentation is 1:1 unmodified from the Format XML schema reference: https://docs.microsoft.com/en-us/powershell/developer/format/format-schema-xml-reference

I can easily update these schemas with new documentation by running the script again, but I don't think it makes sense to apply fixes to the documentation only to the schema? Most people will probably read the docs online. We should decide which one is the source of truth
@SteveL-MSFT

This comment has been minimized.

Sign in to view
Copy link
Member

commented Sep 20, 2018 •
edited

@felixfbecker I submitted MicrosoftDocs/PowerShell-Docs#2943 to fix the online documentation. I'm ok leaving the second comment until we add more to the schema. You can wait for that to be merged and rerun your script.
@lzybkr

This comment has been minimized.

Sign in to view
Copy link
Member

commented Sep 20, 2018

I like the idea of a single source of truth. Maybe we should include your script in this PR so anyone can update the schemas from the docs.
@felixfbecker

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

commented Sep 21, 2018 •
edited

In an ideal world the docs would rather be generated from the schema (there are probably tools out there that do this). Parsing markdown with regexes is really hacky so I'm not sure if we want to rely on that. The current docs are not very well-structured in general so generating them differently would likely do them good.

@SteveL-MSFT your change actually didn't affect my script because it only updated the table of contents, I sent a follow-up PR: MicrosoftDocs/PowerShell-Docs#2944
@felixfbecker

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

commented Sep 21, 2018

My script also detected many cases in the docs where the schema you gave me @lzybkr directly contradicted the reference docs, e.g. an explicit minOccurs="0" in the schema, but an explicit "This element is required" in the docs. I tried out a few cases by omitting the element, loading the file into PowerShell and checking if it errors, and found that in all cases the docs were wrong. So the docs are a bad single source of truth.
@lzybkr

This comment has been minimized.

Sign in to view
Copy link
Member

commented Sep 21, 2018 •
edited

Generating the markdown does sound easier. It doesn't need to be in this PR, but I do like that idea.

And I don't see ever truly having a single source of truth without generating PowerShell's parser from the xsd - but having done that once before, we'd want the generated code to be much better than what I saw a few years ago.
@felixfbecker

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

commented Sep 24, 2018

@lzybkr @SteveL-MSFT updated schemas with latest docs, should be good to merge now.
@SteveL-MSFT

SteveL-MSFT requested changes Sep 24, 2018
View changes

src/Schemas/Types.xsd Outdated
@@ -164,4 +164,4 @@
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:schema>
</xs:schema>

This comment has been minimized.

Sign in to view
Copy link
@SteveL-MSFT

SteveL-MSFT Sep 24, 2018

Member

Please add a trailing newline at the end
@SteveL-MSFT

This comment has been minimized.

Sign in to view
Copy link
Member

commented Sep 24, 2018

@felixfbecker please rebase off master to pick up fixes causing the CI failures
@felixfbecker
Add XSDs for Format and Types.ps1xml files 
These can be used for autocompletion and validation in editors
Loading status checks…
7affb97

@felixfbecker felixfbecker force-pushed the felixfbecker:xsd branch to 7affb97 Sep 24, 2018

@felixfbecker

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

commented Sep 25, 2018

@SteveL-MSFT all green ✅
@SteveL-MSFT

SteveL-MSFT approved these changes Sep 25, 2018
View changes

@SteveL-MSFT SteveL-MSFT assigned adityapatwardhan Sep 25, 2018

@felixfbecker

This comment has been minimized.

Sign in to view
Copy link
Contributor Author

commented Oct 2, 2018

@adityapatwardhan?
@adityapatwardhan

This comment has been minimized.

Sign in to view
Copy link
Member

commented Oct 2, 2018

@felixfbecker Sorry for the delay. I will review this today.
@adityapatwardhan

adityapatwardhan approved these changes Oct 2, 2018
View changes

@adityapatwardhan adityapatwardhan merged commit 97daeb5 into PowerShell:master Oct 2, 2018
8 checks passed

8 checks passed

CodeFactor No issues found.
Details
PowerShell-CI-linux #PR-7832-20180924.02 succeeded
Details
PowerShell-CI-macos #PR-7832-20180924.02 succeeded
Details
PowerShell-CI-spelling #PR-7832-20180924.02 succeeded
Details
PowerShell-CI-windows #PR-7832-20180924.02 succeeded
Details
WIP ready for review
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
license/cla All CLA requirements met.
Details
@adityapatwardhan

This comment has been minimized.

Sign in to view
Copy link
Member

commented Oct 2, 2018

@felixfbecker Thanks for your contribution!

@felixfbecker felixfbecker deleted the felixfbecker:xsd branch Apr 6, 2019

adityapatwardhan added a commit to adityapatwardhan/PowerShell that referenced this pull request Apr 9, 2019

@felixfbecker @adityapatwardhan
Add XSDs for Format and Types.ps1xml files (PowerShell#7832) 
These can be used for autocompletion and validation in editors
8c17d12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.