Formally deprecate the old diagnostics.json digest file #1163
Conversation
| package protocol _DeprecatedConsumeProblemsAccess { | ||
| func _consume(problems: [Problem]) throws | ||
| } | ||
|
|
||
| package struct _Deprecated<Consumer: ConvertOutputConsumer>: _DeprecatedConsumeProblemsAccess { |
There was a problem hiding this comment.
Because ConvertOutputConsumer is a public protocol I had to get a bit creative to be able to still call its deprecated API without introducing deprecation warnings in the DocC code.
There was a problem hiding this comment.
Nice work avoiding the warning!
However, it's hard to follow exactly how this code avoids the warning - specifically, why the use of the _DeprecatedConsumeProblemsAccess protocol allows the call site to avoid a warning since _consume in the protocol is not actually deprecated. Since all the call sites have to both use the special _Deprecated structure and cast to the protocol this explanation would be important.
There was a problem hiding this comment.
I added code comments to explain how this avoids the deprecation warning in 6f89894
| @@ -21,7 +21,6 @@ class TestRenderNodeOutputConsumer: ConvertOutputConsumer { | |||
| } | |||
| } | |||
|
|
|||
| func consume(problems: [Problem]) throws { } | |||
There was a problem hiding this comment.
This tests that conforming types can omit implementing the deprecated method.
rdar://145729962
d-ronnqvist
force-pushed
the
deprecate-old-diagnostics-digest-file
branch
from
67ee22a to
15ac29e
Compare
| package protocol _DeprecatedConsumeProblemsAccess { | ||
| func _consume(problems: [Problem]) throws | ||
| } | ||
|
|
||
| package struct _Deprecated<Consumer: ConvertOutputConsumer>: _DeprecatedConsumeProblemsAccess { |
There was a problem hiding this comment.
Nice work avoiding the warning!
However, it's hard to follow exactly how this code avoids the warning - specifically, why the use of the _DeprecatedConsumeProblemsAccess protocol allows the call site to avoid a warning since _consume in the protocol is not actually deprecated. Since all the call sites have to both use the special _Deprecated structure and cast to the protocol this explanation would be important.
|
@swift-ci please test |
1 similar comment
|
@swift-ci please test |
d-ronnqvist
force-pushed
the
deprecate-old-diagnostics-digest-file
branch
from
3c8590d to
dd7db72
Compare
|
@swift-ci please test |
Bug/issue #, if applicable: rdar://145729962
Summary
This formally deprecates the old "diagnostics.json" digest file that DocC writes when passed the
--emit-digestflag.This file has superseded by the
--diagnostics-file, --diagnostics-output-path <diagnostics-file>file since March 2023 (by #494).With these changes, the deprecated "diagnostics.json" digest file will contain an additional warning that this file is deprecated and will be removed. However, if there are no warnings or errors, the file won't include this deprecation warning to avoid interfering with older systems who read this file as an indication that the build has warnings or not.
Dependencies
None.
Testing
Build any documentation that produces at least one warning and pass the
--emit-digestflag.Inspect the "diagnostics.json" file inside the documentation output. There should be a warning that this file is deprecated and will be removed.
Checklist
Make sure you check off the following items. If they cannot be completed, provide a reason.
./bin/testscript and it succeeded[ ] Updated documentation if necessary