[Doc Transform] Enhance "See" and "SeeAlso" Tag Processing

[jsquire]

Summary

The focus of these changes is to enhance the processing applied to <see> and <seealso> tag processing to address some of the gaps that were observed during docs generation for the Azure SDKs.

Included are:

• Apply the transform used for <see> tags with an href attribue to <seealso> tags for rendering consistency. This allows both tags to render their href as display text when no text was supplied as content in the tag.

• Enhanced "related items" logic to include root-level <seealso> tags with an href as well as <related> tags. This allows both tags to have representation in the YAML. Previously, <seealso> tags not contained within content-based node, such as <summary> or <remarks> were ignored and left out of documentation.

• Added deduplication for <seealso> and altmember tags that share the same cref value. This allows a single "See Also" reference to be generated for the YAML rather than duplicate nodes with the same content.

• Applied the same rules for <see> and <seealso> content extraction to the intellisense generation. This allows the href to be used as the display text when no text was supplied as content in the tag. Previously, these were ignored.

Discussion Items

• It was unclear to me whether the SpecialProcessElement of IntellisenseFileGenHelper should be updated as I'm not sure of the purpose of that output. I made the change to ensure that items the author was expecting to be in the content don't disappear and result in text that reads awkwardly.

Last Upstream Rebase

Thursday, March 4, 1:30pm (EST)

References and Related

• KeyVault Docs: missing private key sample (#18847)
• Task383436:Update ECMA2Yaml xslt to handle empty tag (#178)

[jsquire]

//fyi: @danieljurek

[heaths]

Fixes #166

[TianqiZhang]

@jsquire thank you for your contribution and sorry that we don't have a good contribution guide in place, opened a task (AB#385626) to myself to add one.

We mainly rely on integration test to cover everything, and to test your change, you can do the following:

1. directly add <seealso> tags in /test/xml folder
2. full build the solution with Release configuration
3. run /CI/devopsIntTest.ps1, it will run ECMA2Yaml with test data and compare the result with existing files. Add those changes to the existing files if they are expected.

Don't worry about the build failure in Azure DevOps, our pipeline does not support fork builds very well, as long as your change passed integration test, it's good to go.

[TianqiZhang]

I just realized that @jsquire you've run the integration test and it failed due to some ordering issue. This is possible if you are running from a non-windows machine, and I've pushed a fix in develop branch trying to fix this. Could you please help to sync the latest develop and see if that works for you?

[jsquire]

Hi @TianqiZhang. Thanks very much for your insight and the pointers on next steps. Your fix for making the output deterministic for the integration tests worked for me, and I was able to start in a passing state. I've added coverage for some of the scenarios with <see> and <seealso> tags that we were seeing with the Azure SDKs, which ended up taking me a bit deeper into the woods than I expected.

I didn't seem to end up in any areas with existing unit test coverage, so I followed your guidance and concentrated on the integration test assets. I believe that I've got a good set of coverage for the scenarios in place and the suite is passing.

[TianqiZhang]

@jsquire thanks again for your contribution! PR merged.