Add Single and Double overloads to BinaryPrimitives by eerhardt · Pull Request #6864 · dotnet/runtime (original) (raw)

Choose a reason for hiding this comment

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

Thanks for catching these. :)

Choose a reason for hiding this comment

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

Choose a reason for hiding this comment

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

The docs commented started with the comments from source but then went through doc review and got fixed up (see dotnet/dotnet-api-docs#2693). For new APIs, if you fix them in source, it will make porting them easier.

cc @carlossanlop

Choose a reason for hiding this comment

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

Why don't the fixes from the doc review get ported back into the source?

Choose a reason for hiding this comment

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

We do not have a automated tooling to do that. If we did have one, it would likely require a lot of manual interventions and be expensive to keep running on ongoing basis.

IMHO, the best way to address this would be to make the docs live in just one place, and avoid the duplication.

Choose a reason for hiding this comment

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

the best way to address this would be to make the docs live in just one place, and avoid the duplication.

Totally agree. IMO that one place should be in the source.

Choose a reason for hiding this comment

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

that one place should be in the source.

It is not obvious that it would be the right choice. The documentation is version-agnostic (spans all released and supported versions of .NET Framework and .NET Core), but the sources are version specific.

Choose a reason for hiding this comment

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

We had similar discussions previously with the docs team and given the constraints, decided as having the docs site be the single source of truth. It does have the side effect that you are seeing @eerhardt, but as @jkotas mentioned, trying to keep source and docs in sync is challenging, potentially flaky and may not be a tenable, especially since both the docs and source get updated all the time (from various parties). Given the real customer value is having the docs and Intellisense, we prioritized that as the source of truth and only "seed" them with the xml comments from source once. The higher order bit is to encourage and ensure that we are writing useful, customer facing xml comments that are complete, whenever we add new APIs and make sure the customer benefits from it. Area owners and those adding API/source contribution can manually sync them back if they choose to, but it isn't mandatory.