Skip to content

Document the parameter list each destination type takes - #1785

Merged
blikblum merged 1 commit into
foliojs:masterfrom
MahathirMohammadShuvo:docs-destination-parameter-lists
Aug 28, 2026
Merged

Document the parameter list each destination type takes#1785
blikblum merged 1 commit into
foliojs:masterfrom
MahathirMohammadShuvo:docs-destination-parameter-lists

Conversation

@MahathirMohammadShuvo

Copy link
Copy Markdown
Contributor

What kind of change does this PR introduce?

Documentation. This is the note you said yes to in #1783.

docs/destinations.md showed three worked calls but never stated the parameter lists, and
six of the eight destination types appear nowhere on the page — so for those there was
nothing to infer an arity from at all. The note adds the eight types from ISO 32000-1
Table 151 with their positional parameters, which of them accept null, and what the
zero-argument call produces.

It also names the one conversion the method performs, which is the part I think earns its
place: an XYZ top is flipped against the page height, while FitH, FitBH and FitR's
vertical coordinates are written through unchanged. The page's own two examples already
disagree about the origin —

doc.addNamedDestination('LINK', 'FitH', 100);        // -> [page /FitH 100]
doc.addNamedDestination('LINK', 'XYZ', 36, 36, 50);  // -> [page /XYZ 36 756 50]

— and nothing said so, so a reader who carries the XYZ example's convention into a FitH
call lands at the wrong end of the page.

Every arity and the null rule were checked against the pdfjs-dist in this repo's dev
dependencies, and FitR's parameter order against the way its viewer consumes them
(x = destArray[2], y = destArray[3], width = destArray[4] - x).

One thing worth flagging rather than leaving you to find: the table will render as literal
pipes, because the docs are built with markdown@0.5.0 and the table dialect is not
enabled. docs/getting_started.md and docs/outline.md already ship that way through both
generators, so I matched the neighbours rather than making this page the odd one out — but
say the word and I'll convert it to a bullet list.

I'll close #1783 in favour of this.

Checklist:

  • Unit Tests — n/a, documentation only
  • Documentation
  • Update CHANGELOG.md — n/a, the Unreleased section carries behaviour changes
  • Ready to be merged

The page showed three worked examples of addNamedDestination() but never
said what the parameter lists are, so the arity of each destination type
had to be inferred from them — and six of the eight types appear nowhere on
the page, so for those there was nothing to infer from.

Sets out the eight types from ISO 32000-1 Table 151 with their positional
parameters, which of them accept a null parameter, and what the
zero-argument call produces.

It also names the one conversion this method performs: an XYZ top is
flipped against the page height, so it is given measured from the top of
the page, while FitH, FitBH and FitR's vertical coordinates are written
through unchanged and are measured from the bottom. The page's own two
examples already differ on this and nothing said so.
@blikblum

Copy link
Copy Markdown
Member

Many thanks

@blikblum
blikblum merged commit 70c9ad5 into foliojs:master Aug 28, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants