mapbox / mapbox/mapbox-directions-swift

Documentation lacks method signatures

Open
#759 0 comments 0 reactions 0 assignees View on GitHub
bug build documentation jira-sync-complete op-ex
Dominant language
Swift
Stars
206
Forks
99
Avg merge
7h 54m
Merged PRs (30d)
3

Description

Generating the published documentation for v2.8.0-beta.3 produces a slew of warnings about missing USRs. This causes the generated pages to lack method signatures, and anchors to specific sections of the pages are broken. The warnings start out with something about conflicts:

```
Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: instance method calculate(_:completionHandler:), instance method calculate(_:completionHandler:)
Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: type alias LocationSpeed, type alias LocationSpeed
Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: type alias LocationAccuracy, type alias LocationAccuracy
Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: type alias Color, type alias Color, structure Color
Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: type alias Scale, type alias Scale
Found conflicting type declarations with the same name, which may indicate a build issue or a bug in Jazzy: instance method init(location:heading:name:), instance method init(location:heading:name:)
```

followed by a warning about each of the symbols in this library:

```
`Session` has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an `#if` block, please ignore this message.
`RouteCompletionHandler` has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an `#if` block, please ignore this message.
`MatchCompletionHandler` has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an `#if` block, please ignore this message.
`RouteRefreshCompletionHandler` has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an `#if` block, please ignore this message.
`shared` has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an `#if` block, please ignore this message.
`credentials` has no USR. First make sure all modules used in your project have been imported. If all used modules are imported, please report this problem by filing an issue at https://github.com/realm/jazzy/issues along with your Xcode project. If this token is declared in an `#if` block, please ignore this message.

```

The whole docset is affected:

```
0% documentation coverage with 0 undocumented symbols
```

This issue did not affect the [v2.7.0 documentation](https://docs.mapbox.com/ios/directions/api/2.7.0/). We’ve been seeing something similar with Turf as well: mapbox/turf-swift#195.

/cc @mapbox/navigation-ios

Contributor guide

Open the contributing guide

Research direction

Start by reproducing the v2.8.0-beta.3 published documentation build and reviewing Jazzy's conflicting declaration and missing-USR warnings. Compare the output with the linked v2.7.0 documentation and the Turf example; done means method signatures and section anchors are present across the docset and coverage is no longer reported as 0%.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.