This PR adds some key concepts to both `core-https` and `core-client`, as well as creating a new overview README for the core namespace. This is intended to be a start of more detailed documentation that we can link to when ramping up new library authors.
Suggestion comments are greatly appreciated! 😄
* Add quotes around the parameter
* Add variable group for test options.
Co-authored-by: Wes Haggard <Wes.Haggard@microsoft.com>
Co-authored-by: Wes Haggard <weshaggard@users.noreply.github.com>
* Make the user agent configurable.
* Address comments
* Default to current Chrome version
* Revert the yaml file changes
Co-authored-by: Sima Zhu <sizhu@microsoft.com>
* Add function for retrieving existing versions of packages
* Add SetPackageVersion function
* Update versioning tools
* Add GetPackageInstallNotes function
* Remove changes not related to changelog
* Update latest folder with one index.html includes the redirect links
* Update the redirect links and remove everything in latest
* Address feedback
* Have the entire copy for latest GA.
Co-authored-by: Sima Zhu <sizhu@microsoft.com>
- Add set of helpers to work with devops work items
- Add script to create devops release package items
- Update SemVer to support version type
Co-authored-by: Wes Haggard <Wes.Haggard@microsoft.com>
* [WIP] prototype: multi-service-version test support
* Move multi-version test support into its own package
* Add some unit tests
* Add README
* Fix missing rollup error in CI build
* Disable browser test bundling
* Remove option to specify custom string comparison function
Now it's required to have a sorted list of API version strings
supported by the service from the oldest to the latest. This list is
used to compare version strings.
Add missing `skip` method to the chain object.
Add unit tests
* Fix README analysis issue
* Move `forEach()` and `onVersions()` into `versionsToTest()`
* Ignore README verification errors
* Fix rollup error
* Undo file moves
* Minor README tweak
* Fix build error in pipeline
* Add `DISABLE_MULTI_VERSION_TESTING` env var
# Status quo
Some of our documentation comments are [TypeDoc](http://typedoc.org/guides/doccomments/) and some of them are JSDoc with type description in the comments even though it is for typed TS code.
# Standardization
I decided the best way to go about this is to migrate to [TSDoc](https://github.com/Microsoft/tsdoc) and enforcing it using the [tsdoc eslint plugin](https://www.npmjs.com/package/eslint-plugin-tsdoc).
Pros:
- TSDoc is a proposal to standardize the doc comments used in TypeScript code, so that different tools can extract content without getting confused by each other’s markup.
- It is being developed at Microsoft, with the TypeScript team.
- It has an ESLint plugin that enforces it and will error when it sees unsupported tags (e.g. `@memberof`, `@class`, `@constructor`, `@type`, etc).
Cons:
- It is still in early stages (adoption is ongoing though, e.g. it is being used by the API extractor tool).
- TSDoc != TypeDoc (the tool we currently use for generating our documentation). However, TypeDoc plans to officially support TSDoc in v1.1 (see https://github.com/TypeStrong/typedoc/issues/1266).
# Notable tag changes
- `@ignore` is a JSDoc tag and was used in conjunction with `@internal`. These tags were needed because [TypeDoc does not yet support documenting only definitions exported by the entry point](https://github.com/TypeStrong/typedoc/pull/1184#issuecomment-650809143) and still documents everything exported from all files. I removed `@ignore` because [`@internal`](https://tsdoc.org/pages/tags/internal) only should suffice
- `@ignore` when used alone is replaced with TypeDoc's [`hidden`](http://typedoc.org/guides/doccomments/#hidden-and-ignore). EDIT: I replaced `@ignore` with [`@hidden`](https://github.com/TypeStrong/typedoc/releases/tag/v0.12.0) because the TypeDoc version used for `docs.microsoft.com` is v0.15.0 which does not support `--stripInternal`. After, they upgrade, I will remove all `@hidden` tags.
- `@summary` is gone because it is not part of TSDoc or TypeDoc
This PR applies the changes to packages that respect our linting rules. Ones that do not yet will be migrated later when we start fixing their linting issues.
Here are vanilla examples of TypeDoc 0.18.0 (version used by our EngSys) after the changes here as a sanity check:
- random method:
- a class constructor that used to have type information in the documentation comments:
# `@hidden` works the same way as `@ignore`
Here are the list of documented functions generated by `TypeDoc v0.15.0` for the text analytics package and there is no function that was marked `@hidden`, e.g. `combineSuccessfulAndErroneousDocumentsWithStatisticsAndModelVersion`
# Things to consider
- Our documentation must be generated using the TypeDoc flag [`--stripInternal`](http://typedoc.org/guides/options/#stripinternal)
- Should we add a `docs` npm script to our `package.json`s (similar to [Cosmos's](2424b74f02/sdk/cosmosdb/cosmos/package.json (L60))) so that we can see how our docs are generated as we write our comments?
Fixes https://github.com/Azure/azure-sdk-for-js/issues/3027.
* Support alpha and azure pipeline build version formats for SemVer parsing and sorting
* Minor build number fixes
* Support zero-padding of build versions more generically in SemVer script
* Fix pre-release label conditional for HasValidPrereleaseLabel in semver script
* Set default convention for build number separator in semver script
Co-authored-by: Ben Broderick Phillips <bebroder@microsoft.com>
* reformatted parameter arguments to both update-docs scripts. added parameter requirements and renamed CIRepository to DocRepoLocation which is a lot clearer. Added additional CIConfig parameter to update-docs-metadata to support specific write locations per moniker.
Co-authored-by: scbedd <45376673+scbedd@users.noreply.github.com>
* Fixed the docindex.yml and rename the files
* Reset the mutated changes
* Force checkout as the changes have already copied out
* Minor changes for parameters
* Update Generate-DocIndex.ps1
* Update Generate-DocIndex.ps1
* Update Generate-DocIndex.ps1
* Added function to common
* Update Generate-DocIndex.ps1
Co-authored-by: Sima Zhu <sizhu@microsoft.com>
Co-authored-by: Sima Zhu <48036328+sima-zhu@users.noreply.github.com>
* Move entire docgeneration into common tools
* Move docindex to common
* Added the package replacement logic
* Fixed on parameters
* Fixed param
* Change function to dash
* Added regex on function
* Added display name.
* Update eng/common/docgeneration/Generate-DocIndex.ps1
Co-authored-by: Wes Haggard <weshaggard@users.noreply.github.com>
* Deal with js
* Add no new line args
* revert some test changes
* Need to default to the double quotes for JS regex
* Update Generate-DocIndex.ps1
* Added the appTitle
* type
Co-authored-by: Sima Zhu <sizhu@microsoft.com>
Co-authored-by: Sima Zhu <48036328+sima-zhu@users.noreply.github.com>
Co-authored-by: Wes Haggard <weshaggard@users.noreply.github.com>
Mitch Denny
Azure SDK Bot
Chidozie Ononiwu
Jeff Fisher
KarishmaGhiya
praveenkuttappan
Jeremy Meng
Harsha Nalluru
Deyaaeldeen Almahallawi
Will Temple
Sima Zhu
Scott Beddall
Ramya Rao
