PNG Documentation Issues

Question

PNG Documentation Issues

SDGGiesbrecht opened this issue 6 years ago · 13 comments

SDGGiesbrecht commented 6 years ago

Various issues occur when trying to document the PNG project.

Some discussion has already taken place in the Swift Forums.

Answer 1 · 2018-11-11T12:05:49.000Z

Spun‐off #199: Clarify Warning & Documentation for the Unicode Proofreading Rule

Answer 2 · 2018-11-11T12:31:26.000Z

Spun‐off #200: Callout Colons Mistaken for Inheritance Colons

Answer 3 · 2018-11-11T12:31:48.000Z

Spun‐off #201: Proofreading Hangs on SwiftLint

Answer 4 · 2018-11-11T12:45:47.000Z

Spun‐off #202: Symbols with Attributes Are Dropped

Answer 5 · 2018-11-11T12:46:06.000Z

Spun‐off #203: Array Type Sugar Gets Scrambled

Answer 6 · 2018-11-11T12:46:45.000Z

Spun‐off #204: Generic Parameters Are Dropped

Answer 7 · 2018-11-11T12:47:11.000Z

Spun‐off #205: URLs Are Not Properly Sanitized

Answer 8 · 2018-11-11T12:47:40.000Z

Spun‐off #206: Documentation Comments Not Detected

Answer 9 · 2018-11-11T12:48:00.000Z

Spun‐off #207: Enumeration Cases Missing

Answer 10 · 2018-11-11T12:55:03.000Z

Spun‐off #208: Tuple Types Become Scrambled

Answer 11 · 2018-11-11T19:32:23.000Z

Also related:
#209: Block‐Style Documentation Sometimes Dropped

Answer 12 · 2018-11-11T19:36:21.000Z

Since all the specific bug are now in dedicated issues, including the additional issue I encountered (#209) when setting up validation, I am closing this general issue as dealt with.

Further general questions can be fielded in tayloraswift/swift-png#12.

Answer 13 · 2018-12-20T06:19:11.000Z

@Kelvin13, all the issues you reported have been fixed in the newly released 0.15.0.

I also tried Workspace on the current state of PNG’s master branch before releasing it. Two issues remain. Workspace can do little about either, but both have simple workarounds:

#error(): You use it in three places now. SwiftSyntax crashes when it encounters these. Until Apple releases an update, there is no good solution. At best, Workspace could ignore files that cause SwiftSyntax to crash, but considering how much information would be lost, I don’t think it is worth the effort. There is simply no way to parse anything out of files that contain #error() or #warning(). In your case though, two of the three places you use it are redundant, since a failure to parse the manifest prevents the compiler from ever reaching the targets containing the other two instances. The primary one in the manifest can just be replaced with fatalError(), which will also block the manifest from loading.
@_specialize(): Workspace now accepts the attributes SwiftSyntax knows about, but @_specialize() isn’t one of them, and it causes trouble for SwiftSyntax by breaking up the declaration with intervening garbage text, separating the documentation from the declaration itself. Since it is not part of the published API, I doubt it will make Apple’s priority list any time soon. However, @inlinable does work, and for code vended as a package it should have the same effect. The only difference is instead of being specific, it lets the compiler choose to specialize for any type a client uses it with and leave out any unused specializations. At least that’s what it’s supposed to do; so unless performance tests show a significant slowdown, I would recommend switching to @inlinable. If you don’t want to though, this issue is not as bad, since it does not cause a crash, so if you’d rather, you can just let those documentation comments be dropped for now.

To apply the update to your package, update Workspace on your local device, then using the new version from the command line, refresh the package. $ git diff should reveal several lines in generated files where the version number changed.

You can then restore the documentation coverage check too, since the results will be meaningful again (provided you do something about @_specialize()).