Skip to content

Commit 5303080

Browse files
mikebarkminmikebarkmin
committed
Document only what someone can call
Twenty-three reference pages described the library's own plumbing. Nine took a Processing PGraphics, which nothing in the library hands out, so there was no way to call them and nothing to show. addedToStage and removedFromStage are the methods that call the documented whenAddedToStage and whenRemovedFromStage, and listing both invited overriding the wrong one; on Text and Pen they carried no description at all, so those pages were a bare signature. The rest were Sprite's protected setWidth, setHeight, setNineSlice, disableNineSlice, setUI and isUI - the seams UISprite is built on - plus Shape.invalidateCache. The doclet documents public members only now, so the next protected helper cannot leak in on its own. What is genuinely public but not meant to be called says so with @ignore-in-docs, and says why. The 60 extension pages with no example keep them, because the reason is different: File, Pixels, the recorders, Shader, Sorting and Tiled are real API that cannot run inside a web page. They now say that, from one @desktop-only tag in each extension's package-info.java, which covers whatever is added to them later. A class's constructor moves off the class index onto a constructor page of its own, carrying index 0 so it still sorts first. The index had been carrying both, and the constructor syntax had never rendered at all - the template asked for `constructors` where the doclet writes `constructor`. The reference landing page now warns that a whole double prints without its decimal part in the examples that run in the browser, so `x: 0` there and `x: 0.0` on your own machine is not a surprise.
1 parent 48c7d95 commit 5303080

14 files changed

Lines changed: 292 additions & 67 deletions

File tree

‎.changeset/constructor-pages.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
type: patch
3+
---
4+
5+
Gave each class's constructor a page of its own.
6+
7+
A class used to be documented on the landing page of its own section, which no
8+
navigation ever pointed at. It now has a `constructor` page carrying `index: 0`,
9+
so it sits at the top of the class in the sidebar next to the methods -
10+
`Sprite()` above `addCostume()` - and reads like one of them. The class
11+
description, the example, the constructor syntax and the static fields all moved
12+
there with it. The section's `index` page is left empty; it is the landing page
13+
of the section and nothing more.
14+
15+
The constructor syntax had never appeared on any page: the template asked for
16+
`constructors` while the doclet writes `constructor`, so the block was silently
17+
skipped. It is on the new page, under Syntax, the way a method's syntax is.
18+
19+
A link to a class page, e.g. `/reference/Sprite/`, now arrives at an empty page
20+
rather than at the class documentation, which has moved to
21+
`/reference/Sprite/constructor`. Nothing in the book linked to one.

‎.changeset/reference-only-what-you-can-call.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
type: patch
3+
---
4+
5+
The reference lists only what someone using the library can actually call.
6+
7+
Twenty-three pages documented the library's own plumbing. Nine of them took a
8+
Processing `PGraphics` — `draw`, `drawDebug`, `drawShape` — which nothing in the
9+
library hands out, so there was no way to call them and no example to show.
10+
`addedToStage`/`removedFromStage` are the methods that *call* the documented
11+
`whenAddedToStage`/`whenRemovedFromStage`, and having both listed invited
12+
overriding the wrong one; on `Text` and `Pen` they carried no description at all,
13+
so those pages were a bare signature. The rest were `Sprite`'s protected
14+
`setWidth`, `setHeight`, `setNineSlice`, `disableNineSlice`, `setUI` and `isUI`
15+
— the seams `UISprite` is built on — plus `Shape.invalidateCache`.
16+
17+
The doclet now documents public members only, so a protected helper added later
18+
cannot leak into the reference on its own.
19+
20+
The extension pages that have no example keep them, because the reason is
21+
different: `File`, `Pixels`, the recorders, `Shader`, `Sorting` and `Tiled` are
22+
real API that simply cannot run inside a web page. Those 66 pages now say so, in
23+
a note the doclet places from a single `@desktop-only` tag in each extension's
24+
`package-info.java`.

‎docs/templates/class-constructor.md.hbs‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
name: {{ name }}
3+
index: 0
4+
{{#if hide}}
5+
hide: true
6+
{{/if}}
7+
---
8+
9+
# {{ name }}
10+
11+
{{#if desktopOnly}}
12+
:::alert{info}
13+
14+
This class works in a project you run on your own computer, but not in the
15+
examples you can start here in the browser. There is no file system, no video
16+
encoder and no OpenGL behind a web page, so calling it there tells you as much
17+
and does nothing.
18+
19+
:::
20+
{{/if}}
21+
22+
{{{ description }}}
23+
24+
{{#if examples}}
25+
## Examples
26+
27+
{{#each examples}}
28+
{{#if online}}
29+
:::onlineide{height="460px" libraries="scratch"}
30+
31+
```java Example.java
32+
{{{ online }}}
33+
```
34+
35+
:::
36+
{{else}}
37+
{{#if preview}}
38+
![]({{ concat "/reference/" preview }})
39+
{{/if}}
40+
41+
::::tabs{id="{{{ folder }}}"}
42+
{{#each files}}
43+
:::tab{title="{{{ src }}}" id="{{{ folder }}}.{{{ src }}}"}
44+
```java
45+
{{#if lines}}
46+
{{{ rfile (concat "/src/examples/java/reference/" ../folder "/" src) lines "" }}}
47+
{{else}}
48+
{{{ rfile (concat "/src/examples/java/reference/" ../folder "/" src) }}}
49+
{{/if}}
50+
```
51+
:::
52+
{{/each}}
53+
::::
54+
{{/if}}
55+
56+
[View on GitHub](https://github.com/openpatch/scratch-for-java/blob/main/src/examples/java/reference/{{#if folder}}{{ folder }}{{else}}{{#with (lookup files 0)}}{{ src }}{{/with}}{{/if}})
57+
{{/each}}
58+
{{/if}}
59+
60+
{{#if constructor}}
61+
## Syntax
62+
63+
### Java
64+
```java
65+
{{#each constructor}}
66+
{{{this}}}
67+
{{/each}}
68+
```
69+
{{/if}}
70+
71+
{{#if fields}}
72+
## Static Fields
73+
74+
| Name | Type | Description |
75+
|------|------|-------------|
76+
{{#each fields}}
77+
| `{{ name }}` | {{ type }} | {{ description }} |
78+
{{/each}}
79+
{{/if}}

‎docs/templates/class-method.md.hbs‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,32 @@ hide: true
1010

1111
# {{ class }}::{{ name }}
1212

13+
{{#if desktopOnly}}
14+
:::alert{info}
15+
16+
This works in a project you run on your own computer, but not in the examples
17+
you can start here in the browser. There is no file system, no video encoder and
18+
no OpenGL behind a web page, so calling it there tells you as much and does
19+
nothing.
20+
21+
:::
22+
{{/if}}
23+
1324
{{{ description }}}
1425

1526
{{#if examples}}
1627
## Examples
1728

1829
{{#each examples}}
30+
{{#if online}}
31+
:::onlineide{height="460px" libraries="scratch"}
32+
33+
```java Example.java
34+
{{{ online }}}
35+
```
36+
37+
:::
38+
{{else}}
1939
{{#if preview}}
2040
![]({{ concat "/reference/" preview }})
2141
{{/if}}
@@ -33,8 +53,12 @@ hide: true
3353
:::
3454
{{/each}}
3555
::::
56+
{{/if}}
3657

37-
[View on GitHub](https://github.com/openpatch/scratch-for-java/blob/main/src/examples/java/reference/{{ folder }})
58+
{{! An example is either a folder of files or a single file next to them, and
59+
the link has to point at whichever one it is - without the folder there is
60+
nothing left of the path but the directory the examples all share. }}
61+
[View on GitHub](https://github.com/openpatch/scratch-for-java/blob/main/src/examples/java/reference/{{#if folder}}{{ folder }}{{else}}{{#with (lookup files 0)}}{{ src }}{{/with}}{{/if}})
3862
{{/each}}
3963
{{/if}}
4064

‎docs/templates/class.md.hbs‎

Lines changed: 5 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
{{!
2+
The landing page of a class section. It is deliberately empty: the class
3+
itself is documented on its constructor page, which sorts first because it
4+
carries index 0.
5+
}}
16
---
27
name: {{ name }}
38
{{#if index}}
@@ -7,46 +12,3 @@ index: {{ index }}
712
hide: true
813
{{/if}}
914
---
10-
11-
# {{ name }}
12-
13-
{{{ description }}}
14-
15-
{{#if examples}}
16-
## Examples
17-
18-
{{#each examples}}
19-
{{#if preview}}
20-
![]({{ concat "/reference/" preview }})
21-
{{/if}}
22-
23-
```java
24-
{{#if lines}}
25-
{{{ rfile (concat "/src/examples/java/reference/" src) lines "" }}}
26-
{{else}}
27-
{{{ rfile (concat "/src/examples/java/reference" src) }}}
28-
{{/if}}
29-
```
30-
31-
[View on GitHub](https://github.com/openpatch/scratch-for-java/blob/main/src/examples/java/reference/{{ src }})
32-
{{/each}}
33-
{{/if}}
34-
35-
{{#if constructors}}
36-
## Constructors
37-
38-
{{#each constructors}}
39-
- {{this}}
40-
{{/each}}
41-
{{/if}}
42-
43-
{{#if fields}}
44-
## Static Fields
45-
46-
| Name | Type | Description |
47-
|------|------|-------------|
48-
{{#each fields}}
49-
| `{{ name }}` | {{ type }} | {{ description }} |
50-
{{/each}}
51-
{{/if}}
52-

‎docs/templates/package.md.hbs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,17 @@ hide: true
1010

1111
# {{ name }}
1212

13+
{{#if desktopOnly}}
14+
:::alert{info}
15+
16+
Everything in here works in a project you run on your own computer, but not in
17+
the examples you can start in the browser. There is no file system, no video
18+
encoder and no OpenGL behind a web page, so calling it there tells you as much
19+
and does nothing.
20+
21+
:::
22+
{{/if}}
23+
1324
{{{ description }}}
1425

1526
{{#if examples}}

‎src/main/java/org/openpatch/scratch/extensions/fs/package-info.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* Provides classes and interfaces for file system extensions in Scratch.
33
* @name-in-docs File System
4+
* @desktop-only
45
*/
56
package org.openpatch.scratch.extensions.fs;

‎src/main/java/org/openpatch/scratch/extensions/pixels/package-info.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
/**
2+
* Provides read access to the raw pixels of the stage's buffers.
3+
* @name-in-docs Pixels
4+
* @desktop-only
5+
*/
6+
package org.openpatch.scratch.extensions.pixels;

‎src/main/java/org/openpatch/scratch/extensions/recorder/package-info.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* Provides classes and interfaces for recorder extensions in Scratch.
33
* @name-in-docs Recorder
4+
* @desktop-only
45
*/
56
package org.openpatch.scratch.extensions.recorder;

‎src/main/java/org/openpatch/scratch/extensions/shader/package-info.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/**
22
* Provides classes and interfaces for shader extensions in Scratch.
33
* @name-in-docs Shader
4+
* @desktop-only
45
*/
56
package org.openpatch.scratch.extensions.shader;

0 commit comments

Comments
 (0)