Default exports required for deno doc?

[CalvinWilkinson]

I was poking around JSR so I can learn and eventually publish my package to JSR. During this process, I was trying out the deno doc --lint command and came across something that was confusing to me. I am not sure if this is a bug or not or if it is just me not fully understanding something.

IssueOrPRRequestData.ts

I ran the command deno doc --lint against a file named IssueClient.ts. Doing this showed the following results:

error[private-type-ref]: public type 'IssueClient.prototype.updateIssue' references private type 'IssueOrPRRequestData'
   --> K:\SOFTWARE-DEV\PERSONAL\kd_clients\GitHubClients\IssueClient.ts:343:2
    |
343 |   public async updateIssue(issueNumber: number, issueData: IssueOrPRRequestData): Promise<void> {
    |   ^
    = hint: make the referenced type public or remove the reference
    |
  4 | import { LabelModel } from "../deps.ts";
    |                                     - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error: Found 1 documentation lint error.

So with my understanding of the lint error, it is saying that IssueOrPRRequestData.ts is private and not public. So this confuses me because I know for a fact that the interface is exported using the export keyword. I open the file of course discover that this is the case.

Here is the IssueOrPRRequestData.ts file

import { IssueState, StateReason } from "./Enums.ts";

/**
 * Represents the body of an HTTP GitHub API issue request.
 * Used to update an issue or pull request.
 */
export interface IssueOrPRRequestData {
	/**
	 * Gets or sets the title of the issue.
	 */
	title?: string | null | number;

	/**
	 * Gets or sets the contents of the issue.
	 */
	body?: string | null;

	/**
	 * Gets or sets the state of the issue.
	 * @remarks Can be one of: open, closed
	 */
	state?: IssueState;

	/**
	 * Gets or sets the reason for the state change.
	 * @remarks Ignored unless state has changed.
	 * Can be one of: completed, not_planned, reopened, null
	 */
	state_reason?: StateReason | null;

	/**
	 * Gets or sets the number of the milestone to associate the issue with.
	 * @remarks Use null to remove the current milestone. Only users with push access
	 * can set the milestone for issues. Without push access to the repository,
	 * milestone changes are silently dropped.
	 */
	milestone?: string | number | null;

	/**
	 * Gets or sets the labels associated with this issue.
	 * @remarks Pass one or more labels to replace the set of labels on this issue.
	 * Send an empty array ([]) to clear all labels from the issue. Only users with
	 * push access can set labels for issues. Without push access to the repository,
	 * label changes are silently dropped.
	 */
	labels?: string[];

	/**
	 * Gets or sets the usernames to assign to this issue.
	 * @remarks Pass one or more user logins to
	 * replace the set of assignees on this issue. Send an empty array ([]) to clear all assignees
	 * from the issue. Only users with push access can set assignees for new issues.
	 * Without push access to the repository, assignee changes are silently dropped.
	 */
	assignees?: string[];
}

So using my gut feeling, I converted the interface from an export to an export default interface like the below:

- export interface IssueOrPRRequestData {
+ export default interface IssueOrPRRequestData {

I executed the deno doc --lint command again and the lint error went away.

Questions:

1. Is this intentional?
   • I did not find anything in the docs about having to use default exports to get the doc linting to work.
2. What is going on with line 4 in the lint error? 👉🏻 import { LabelModel } from "../deps.ts";
   • Why is it even talking about line r and the LabelModel? How does this have anything to do with IssueOrPRRequestData being public or private?
3. What does the statement in the lint error info: to ensure documentation is complete all types that are exposed in the public API must be public really mean? Isn't an export and export default both considered public?

I hope you can see my confusion here.

Of course, I could have missed it in the documents, and in this case, it is on me.

Any info on this matter would be great!

Thanks!

[marvinhagemeister]

This sounds like the error message is a bit confusing. The public and private visibility is more about it being reachable from one of the package entry points, rather then if the type in question has the export keyword in front of it. Like for example, can I do this in with your package?

// Can users import this type from your package?
import { IssueOrPRRequestData } from "@example/your-package";

Or is the IssueOrPRRequestData not reachable from any of the package entry points? If it is not, then the type is deemed as being "private". The reason that it works with the default export might hint at a bug.

[CalvinWilkinson]

ok. To help clarify some things, what do you exactly mean by "package entry point"?

Right now, if somebody wants to use my package, they can do the usual imports into an exact file or into a mod.ts file. Is this what you mean by "package entry points"?

For example, if somebody wanted to use the issue client, they could do this:

import { IssueClient } from "https://deno.land/x/[email protected]/GitHubClients/IssueClient.ts";

// or

import { IssueClient } from "https://deno.land/x/[email protected]/GitHubClients/mod.ts";

For the IssueOrPullRequestData, they can do this:

import { IssueOrPRRequestData } from "https://deno.land/x/[email protected]/core/IssueOrPRRequestData.ts";

[marvinhagemeister]

JSR introduces the notion of packages in Deno. The older deno.land/x registries doesn't have such a concept. You can think of that one being more of an extension of the local file system. Some files are in your project directory, and some files are pulled remotely from deno.land/x. There is no concept of a package.

With JSR this concept of packages is introduced. The point of a package is that the author can decide which functions and which types users should depend on. Whereas with deno.land/x every file is public and every export was directly accessible, this is not the case with JSR. In JSR you have a few entry points in your module and consumers of said package only have access to whatever is exported there.

Let me illustrate with an example:

// internal.ts
export const strA = "A";
export const strB = "B";

// a.ts
import { strA } from "./internal.ts";
export const A = strA;

// b.ts
import { strB } from "./internal.ts";
export const B = strB;

And your deno.json/jsr.json might have something like this:

{
  "name": "@example/my-package",
  "version": "1.0.0",
  // This defines what kind of types, values, functions, etc consumers of the
  // package can import. Any file not referenced here cannot be imported.
  // These are referred to as package entry points.
  "exports": {
    "./a": "./a.ts",
    "./b": "./b.ts"
  }
}

The way users import that is like this:

import { A } from "jsr:@example/my-package/a"
import { B } from "jsr:@example/my-package/b"

What they cannot do is this:

// Won't work because not a package entry point. Will throw an error.
import { strA, strB } from "jsr:@example/my-package/private.ts"

tl;dr: deno.land/x has no concept of packages, it's just an extension to the local file system. JSR introduces proper packages, only the things that are reachable from a package entry point are considered public. Consumers won't have access to anything else.

[CalvinWilkinson]

Ah ok! Perfect!

Thank you for the explanation. This is making more sense now.

So one thing is I do not have a jsr.json file. I assume that you MUST have a jrs.json for the system to properly have entry points?

[CalvinWilkinson]

Nevermind @marvinhagemeister. I found the docs on this subject. I am good to go.

Thank you so much for your help.

[CalvinWilkinson]

I apologize @marvinhagemeister.

I reopened the conversation because I ran into issues. I started the conversion process by following the docs and using the migration tool.

I am running the deno doc—-lint command and still encountering the same issues.

Here is the feature branch that I have set up with some of the conversion stuff set up.
kd_clients:feature/72-migrate-to-jsr

Would you mind checking out the project/branch and see where I might be going wrong?

It is with the IssueClient.

[marvinhagemeister]

Deferring to @crowlKats who works on deno doc and has a deeper understanding of what's going on than me.

[dsherret]

@CalvinWilkinson I looked into this a bit and it looks like the diagnostics were displaying incorrectly when the referenced type was in a separate module. I opened a fix here: denoland/deno_doc#576

Once that fix lands in Deno, the diagnostics for that project I get are (note I've included all the entrypoints of the package in the deno doc --lint command... would be nice if Deno did this automatically):

# note: this command currently panics in the latest Deno
> deno doc --lint mod.ts ./OtherClients/mod.ts ./GitHubClients/mod.ts ./core/mod.ts ./GitHubClients/Errors/mod.ts ./core/Models/mod.ts
error[private-type-ref]: public type 'IssueClient.prototype.getIssues' references private type 'IssueOrPRState'
   --> V:\kd_clients\GitHubClients\IssueClient.ts:122:2
    |
122 |   public async getIssues(
    |   ^
    = hint: make the referenced type public or remove the reference
    |
  4 | export enum IssueOrPRState {
    | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'MilestoneClient.prototype.getIssuesAndPullRequests' references private type 'IssueOrPR'
  --> V:\kd_clients\GitHubClients\MilestoneClient.ts:78:2
   |
78 |   public async getIssuesAndPullRequests(
   |   ^
   = hint: make the referenced type public or remove the reference
   |
12 | export type IssueOrPR = IssueModel | PullRequestModel;
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'OrgClient.prototype.getPrivateMembers' references private type 'OrgMemberRole'
   --> V:\kd_clients\GitHubClients\OrgClient.ts:60:2
    |
 60 |   public async getPrivateMembers(
    |   ^
    = hint: make the referenced type public or remove the reference
    |
356 | export enum OrgMemberRole {
    | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'ProjectClient' references private type 'GraphQlClient'
  --> V:\kd_clients\GitHubClients\ProjectClient.ts:18:1
   |
18 | export class ProjectClient extends GraphQlClient {
   | ^
   = hint: make the referenced type public or remove the reference
   |
 9 | export abstract class GraphQlClient {
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'PullRequestClient.prototype.getPullRequests' references private type 'MergeState'
  --> V:\kd_clients\GitHubClients\PullRequestClient.ts:92:2
   |
92 |   public async getPullRequests(
   |   ^
   = hint: make the referenced type public or remove the reference
   |
39 | export enum MergeState {
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'WorkflowClient.prototype.getWorkflowRuns' references private type 'AnyBranch'
  --> V:\kd_clients\GitHubClients\WorkflowClient.ts:50:2
   |
50 |   public async getWorkflowRuns(
   |   ^
   = hint: make the referenced type public or remove the reference
   |
17 | export type AnyBranch = null;
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'WorkflowClient.prototype.getWorkflowRuns' references private type 'WorkflowEvent'
   --> V:\kd_clients\GitHubClients\WorkflowClient.ts:50:2
    |
 50 |   public async getWorkflowRuns(
    |   ^
    = hint: make the referenced type public or remove the reference
    |
219 | export enum WorkflowEvent {
    | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'WorkflowClient.prototype.getWorkflowRuns' references private type 'WorkflowRunStatus'
   --> V:\kd_clients\GitHubClients\WorkflowClient.ts:50:2
    |
 50 |   public async getWorkflowRuns(
    |   ^
    = hint: make the referenced type public or remove the reference
    |
241 | export enum WorkflowRunStatus {
    | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'XClient' references private type 'WebApiClient'
  --> V:\kd_clients\OtherClients\XClient.ts:10:1
   |
10 | export class XClient extends WebApiClient {
   | ^
   = hint: make the referenced type public or remove the reference
   |
 6 | export abstract class WebApiClient {
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\OtherClients\Errors\XError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[private-type-ref]: public type 'GitHubClient.prototype.getAllData' references private type 'GetDataFunc'
  --> V:\kd_clients\core\GitHubClient.ts:96:2
   |
96 |   protected async getAllData<T>(
   |   ^
   = hint: make the referenced type public or remove the reference
   |
22 | export type GetDataFunc<T> = (page: number, qtyPerPage?: number) => Promise<[T[], Response]>;
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'IssueOrPRRequestData["state"]' references private type 'IssueState'
  --> V:\kd_clients\core\IssueOrPRRequestData.ts:22:2
   |
22 |   state?: IssueState;
   |   ^
   = hint: make the referenced type public or remove the reference
   |
24 | export enum IssueState {
   | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[private-type-ref]: public type 'IssueOrPRRequestData["state_reason"]' references private type 'StateReason'
   --> V:\kd_clients\core\IssueOrPRRequestData.ts:29:2
    |
 29 |   state_reason?: StateReason | null;
    |   ^
    = hint: make the referenced type public or remove the reference
    |
321 | export enum StateReason {
    | - this is the referenced type

  info: to ensure documentation is complete all types that are exposed in the public API must be public


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\GitError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\IssueError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\LabelError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\MilestoneError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\OrganizationError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\ProjectError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\PullRequestError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\ReleaseError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\RepoError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\TagError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\UsersError.ts:7:2
  |
7 |   constructor(message: string, httpStatusCode?: number) {
  |   ^


error[missing-jsdoc]: exported symbol is missing JSDoc documentation
 --> V:\kd_clients\GitHubClients\Errors\WorkflowError.ts:5:2
  |
5 |   constructor(message: string) {
  |   ^


error: Found 25 documentation lint errors.

Looking at a few of the private-type-ref diagnostics, it looks like those types are not exported from any entrypoint of the package and the user doesn't have a way to access those symbols directly, so that's why those errors occur. You can suppress this by marking those types with an /** @internal */ jsdoc comment if you'd like.

By the way, the deno doc --lint command is not required to use to publish to JSR, but I'm glad you're trying it out. It should help you end up with a better documented package.

[CalvinWilkinson]

@dsherret Thanks for looking into this!! Greatly appreciate it. :)

I do realize that I don't have to use the deno doc --lint command to publish. I think it is a great idea to help encourage people to document their packages. I take personally documentation seriously and all of my projects are well-documented so it was great to see this being such a part of deno as well as JSR.

You guys are doing great work here! 😀

[CalvinWilkinson]

So, just to clarify about exports, I have a few questions I was hoping you could answer.

Few questions:

1. The only requirement is to point to a file with exports in it and the type being exported is considered public, correct?
2. Also, can I point just to a file directly like this?

    "exports": {
        "./client": "./GitHubClients/IssueClient.ts"
    },

3. Can the keys end with a /, and if so, what does that mean?

    "exports": {
        ".": "./mod.ts",
        "./packaging/": "./PackageClients/mod.ts", 
        "./github/": "./GitHubClients/mod.ts",
    },

4. Can the paths point to a folder path instead of a file path and everything in that folder gets exported?

    "exports": {
        ".": "./mod.ts",
        "./github": "./GitHubClients",
    },

Also, do you know when that fix will make it out to deno?