Adding .NET docs for Events to API reference

[kemerava]

Describe your change

Adding .NET docs for Events to API reference
@bingenito hope I did not steal your issue! :) I really wanted to try to give it a go, could you please review it, as I was not sure if there are better ways of implementing it in some places.

Related Issue

resolves #1318

Contributor License Agreement

• I acknowledge that a contributor license agreement is required and that I have one in place or will seek to put one in place ASAP.

Review Checklist

• Issue: If a change was made to the FDC3 Standard, was an issue linked above?
• CHANGELOG: Is a CHANGELOG.md entry included?
• API changes: Does this PR include changes to any of the FDC3 APIs (DesktopAgent, Channel, PrivateChannel, Listener, Bridging)?
  • Docs & Sources: If yes, were both documentation (/docs) and sources updated?
    
    JSDoc comments on interfaces and types should be matched to the main documentation in /docs
  • Conformance tests: If yes, are conformance test definitions (/toolbox/fdc3-conformance) still correct and complete?
    
    Conformance test definitions should cover all required aspects of an FDC3 Desktop Agent implementation, which are usually marked with a MUST keyword, and optional features (SHOULD or MAY) where the format of those features is defined
  • Schemas: If yes, were changes applied to the Bridging and FDC3 for Web protocol schemas?
    
    The Web Connection protocol and Desktop Agent Communication Protocol schemas must be able to support all necessary aspects of the Desktop Agent API, while Bridging must support those aspects necessary for Desktop Agents to communicate with each other
    • If yes, was code generation (npm run build) run and the results checked in?
      
      Generated code will be found at /src/api/BrowserTypes.ts and/or /src/bridging/BridgingTypes.ts
• Context types: Were new Context type schemas created or modified in this PR?
  • Were the field type conventions adhered to?
  • Was the BaseContext schema applied via allOf (as it is in existing types)?
  • Was a title and description provided for all properties defined in the schema?
  • Was at least one example provided?
  • Was code generation (npm run build) run and the results checked in?
    
    Generated code will be found at /src/context/ContextTypes.ts
• Intents: Were new Intents created in this PR?
  • Were the intent name prefixes and other naming conventions & characteristics adhered to?
  • Was the new intent added to the list in the Intents Overview?

[netlify]

✅ Deploy Preview for fdc3 ready!

Name	Link
🔨 Latest commit	406db09
🔍 Latest deploy log	https://app.netlify.com/sites/fdc3/deploys/67af3cacf838700008091421
😎 Deploy Preview	https://deploy-preview-1441--fdc3.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[kemerava]

Sorry @bingenito, had to resolve the merge conflicts, could please re-review?

[kriswest]

The tab selection headers are not appearing on Events.md, e.g.:

https://deploy-preview-1441--fdc3.netlify.app/docs/next/api/ref/Events
vs.

https://deploy-preview-1441--fdc3.netlify.app/docs/next/api/ref/DesktopAgent

That's probably because that page needs the following to be added at the top, right after the metadata block:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

See DesktopAgent.md for an example.

Regarding the definitions contained in the PR, all looks good to me, but I wonder if the Details class might need a better-scoped name such as EventDetails or Fdc3EventDetails. There are already two different sub-classes (both called Details currently) for the channel changed event and Private Channel addContextListener/unsubscribe events, should they be better namespaced? Happy to defer to you and @bingenito on that, but thought to ask.

[kemerava]

Thanks for the review @kriswest! Fixed the imports. I like the EventDetails idea, however, would love to hear also what @bingenito thinks! Thanks both

[bingenito]

I favor Fdc3EventDetails but this is also a placeholder. I've started the implementation of this (copying these as the definition) and will work out where it makes sense to change once we write tests against it and get a feel for naming. We can then circle back and update the docs to match?

[bingenito]

@kemerava I worked on and off over break for weeks on this and can't get it to work intuitively using generics. The design simply just doesn't fit into .NET that well and my current implementation is a back to a greatly simplified IFdc3Event with string type and object? Details. IApiEvent is abandoned right now for me as there would be no difference between the two interfaces given .NET can not restrict on a string enum like we see in TypeScript.

[bingenito]

Draft fdc3-dotnet implementation can be found at finos/fdc3-dotnet#170. As noted above this is significant simplification of design to simply have a nullable object in the base type. As we can't have restriction on enum string values it also didn't make sense to have separate ApiEvent and Fdc3Event definitions. Let's have the discussion over there and then we can circle back here.

[kemerava]

@bingenito @kriswest updated the code based on the .NET PR, please review - thanks!

[kriswest]

I think we should explain the lack of an ApiEvent definition in .NET - see inline comments

[kriswest]

Thanks for the updates @keemereva. I think we're still lacking definitions for the addEventListener functions, see:

• https://deploy-preview-1441--fdc3.netlify.app/docs/next/api/ref/DesktopAgent#addeventlistener
• https://deploy-preview-1441--fdc3.netlify.app/docs/next/api/ref/PrivateChannel#addeventlistener

Don't forget to also add it to the interface definition at the top of each page.

Otherwise LGTM!

[kemerava]

Hi @bingenito, @kriswest added the addEventListener function, hopefully I found all the places were it is needed, and resolved the merge conflicts. Please let me know if any more changes are required! Thanks

[kriswest]

LGTM - many thanks!

[kriswest]

Ignoring failing check - review comment with tests passed failed due to PR coming from a fork as per issue #1519