You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The content for the reference lives inside the `/content/references` folder. This folder has two subfolders:
3
+
The content for the reference lives inside [`/content/references`](https://github.com/processing/processing-website/tree/main/content/references). This folder has two subfolders, `translations` and `examples`:
4
4
5
-
- The `/translations` folder contains a separate folder for every language with `en` being the default one.
5
+
## `/translations`
6
6
7
-
**The `en`folder should never be edited manually since it is auto-generated from the Processing and core libraries source codes.**. This folder is divided into subfolders that correspond to each of the processing libraries and a `processing` folder that contains the core processing reference.
7
+
This folder contains a separate folder for every language, with `en` being the default one. Each json file within the folders will be rendered as a web reference page.
8
8
9
-
The subfolders:
9
+
**Most of the files in the `en` folder should not be edited manually since they are auto-generated from Javadoc annotations in the Processing and core libraries source codes using the [Doclet script](https://github.com/processing/processing-doclet/blob/main/README.md).** Web reference files within `en` that are created and edited manually generally fall into one of two categories:
10
10
11
-
-`/content/references/translations/en/io`
12
-
-`/content/references/translations/en/net`
13
-
-`/content/references/translations/en/processing`
14
-
-`/content/references/translations/en/serial`
11
+
- Java documentation: This includes keywords that are NOT part of the Processing API but good to include as a reference for learners. The `+=` or `/=` operators and some Java keywords like `void` or `static` fall into that category for example, as well as Java primitives such as [`int`](https://github.com/processing/processing-website/blob/main/content/references/translations/en/processing/int.json), [`String`](https://github.com/processing/processing-website/blob/main/content/references/translations/en/processing/String.json) etc. The corresponding json files must be edited manually within the `processing-website` repo.
12
+
- event callback methods which need to be implemented in sketches (and which don't have corresponding methods inside the processing source code that could be annotated with Javadoc), for example [`captureEvent()`](https://github.com/processing/processing-website/blob/main/content/references/translations/en/video/captureEvent_.json)
15
13
16
-
are generated from the [Processing 4](https://github.com/processing/processing4) source code.
14
+
The folder is divided into subfolders that correspond to each of the core libraries and a `processing` folder that contains the core processing reference.
17
15
18
-
The subfolder `/content/references/translations/en/sound` is generated from the [Sound](https://github.com/processing/processing-sound) source code.
16
+
- Generated from the [`processing4`](https://github.com/processing/processing4) source code:
17
+
-`/content/references/translations/en/io`
18
+
-`/content/references/translations/en/net`
19
+
-`/content/references/translations/en/processing`
20
+
-`/content/references/translations/en/serial`
21
+
- Generated from the [`processing-sound`](https://github.com/processing/processing-sound) source code:
22
+
-`/content/references/translations/en/sound`
23
+
- Generated from the [`processing-video`](https://github.com/processing/processing-video) source code:
24
+
-`/content/references/translations/en/video`
19
25
20
-
The subfolder `/content/references/translations/en/video` is generated from the [Video](https://github.com/processing/processing-video) source code.
26
+
Libraries DFX Export, PDF Export and SVG Export don't have individual references so their pages are created from Markdown files in [`content/pages/libraries`](https://github.com/processing/processing-website/tree/master/content/pages/libraries). The intro blurbs to each of the core libraries are also found in this folder.
21
27
22
-
Libraries DFX Export, PDF Export and SVG Export don't have individual references so their pages are created from [here](https://github.com/processing/processing-website/tree/master/content/pages/libraries).
28
+
See the [`processing-doclet`](https://github.com/processing/processing-doclet/blob/main/README.md) instructions on how to generate the json files after having made changes to the reference in any of the Java source files.
23
29
24
-
- The `/examples` folder contains all the examples used inside the references. They are organized in the same folder structure as the `translations` folder. These folders contain all the `.pde` and `.png` files necessary for the examples. Each example image should have a size of `800x800px` and should be named after the corresponding example, e.g. the `bezier_0.pde` example has an image named `bezier_0.png`.
30
+
### Javadoc annotations
25
31
26
-
## Adding content to the english reference
32
+
The doclet script converts the Javadoc annotations to a json file for every class, field or method annotated with a `@webref` tag. (Note: [GitHub search only works for files smaller than 384 KB](https://docs.github.com/en/search-github/searching-on-github/searching-code#considerations-for-code-search) which means [PApplet.java](https://github.com/processing/processing4/blob/main/core/src/processing/core/PApplet.java) is NOT searchable using GitHub's code search feature.)
27
33
28
-
The `content/references/translations/en` folder contains two kinds of json files:
29
-
* Processing API documentation: these files are generated from the processing4 repo using the [Doclet script](https://github.com/processing/processing-doclet/blob/main/README.md) as explained below.
30
-
* Java documentation: This includes keywords that are NOT part of the Processing API but good to include as a reference for learners. The `+=` or `/=` operators and some Java keywords like `void` or `static` fall into that category for example. The corresponding json files must be edited manually within the `processing-website` repo.
34
+
Unlike standard Javadoc (where every method signature gets its own documentation), all methods with the same name are pooled together into one reference page (even static and non-static methods of the same name only get one json file!). Only one of the overloaded methods needs to have a `@webref` tag. The `@` annotations of all methods with the same name will be pooled together in one json file.
31
35
32
-
In each source file, look for the `@webref` tag in the block comments. This tag means that the block will be picked up by the Doclet script and converted into a json file to be included on the website. Note: [GitHub search only works for files smaller than 384 KB](https://docs.github.com/en/search-github/searching-on-github/searching-code#considerations-for-code-search) which means [PApplet.java](https://github.com/processing/processing4/blob/main/core/src/processing/core/PApplet.java) is NOT searchable using GitHub's code search feature.
36
+
A typical Javadoc block will look like this:
33
37
34
38
```
35
-
/*
36
-
* Description
39
+
/**
40
+
* This is a full length description of this method or field, and what it does. It can be as long or short as you want.
37
41
*
42
+
* Line breaks are <em>ignored</em>, so the first sentence and this one are displayed in the same paragraph. If you want to split the descriptions into paragraphs, use line break tags, like so:
43
+
* <br/><br/>
44
+
* It is not unusual for descriptions to have more than one paragraph, so go for it.
45
+
*
46
+
* <h3>Advanced</h>
38
47
* Advanced description
39
48
*
40
49
* @webref category:subcategory
41
-
* @webBrief
50
+
* @webBrief This is a <em>short</em> description of the method that's shown on the reference index page, and also on the method listing of the class page if this is a class method.
51
+
* @param someArg the meaning or purpose of this method argument, allowed range etc.
52
+
* @param anotherArg same thing but for another argument
53
+
* @return <b>true</b> if one thing is the case, <b>false</b> otherwise
54
+
* @see AnotherClass#anotherField
55
+
* @see YetAnotherClass#anotherMethod()
42
56
* ...
43
57
*/
58
+
public boolean someMethod(int someArg, float anotherArg) {
59
+
...
44
60
```
45
61
46
-
**Description:** this should be the main description of the reference. Note: if necessary you can look up the previous reference in the archived XML files located [here](https://github.com/processing/processing-docs/tree/master/content/api_en) under the `<description>` tag.
47
-
48
-
**Advanced description:** this is the advanced description that doesn't go on the webpage but in the in the expanded Java documentation. The advanced description starts with an html heading (e.g. `<h3>Advanced:</h3>`). Advanced description always goes below the Description, though not every reference has an advanced description.
49
-
50
-
**@webref:** tag that implies the reference goes on the website. It is followed by category and subcategory, if they exist, in the format category:subcategory. The category and subcategory are also in the XML files [here](https://github.com/processing/processing-docs/tree/master/content/api_en) under the <category> and <subcategory> tag.
62
+
-**Description:** this should be the main description of the reference. Note: if necessary you can look up the previous reference in the archived XML files located [here](https://github.com/processing/processing-docs/tree/master/content/api_en) under the `<description>` tag.
63
+
-**Advanced description:** this is the advanced description that doesn't go on the webpage but in the in the expanded Java documentation. The advanced description starts with an html heading (e.g. `<h3>Advanced:</h3>`). Advanced description always goes below the Description, though not every reference has an advanced description.
64
+
-**@webref:** only classes, methods and fields with this tag will have a json file generated for them, and therefore go on the website. It is followed by category and subcategory, if they exist, in the format category:subcategory (the subcategory is optional). The category and subcategory are also in the XML files [here](https://github.com/processing/processing-docs/tree/master/content/api_en) under the <category> and <subcategory> tag.
65
+
- for methods that are tagged with `@webref ...:method` a reference page will be created and linked to from the class constructor page, but it will not be included in the web reference index (see for example the methods of [`PVector`](https://processing.org/reference/PVector.html))
66
+
-**@webBrief:** this is the short version of description, just one sentence which is usually the same or very similar to the first sentence of the Description. If the first sentence is too long or doesn't explain the reference, you can change it for a summary of the whole description.
67
+
-**@see Classname**, **@see Classname#field**, **@see Classname#method()**: these will be linked to from the *Related* section at the bottom of the reference page.
68
+
-**...:** everything else that was already in the comment should stay there below the @webBrief tag
51
69
52
-
**@webBrief:** this is the short version of description, just one sentence which is usually the first sentence of the Description. If the first sentence is too long or doesn't explain the reference, you can change it for a summary of the whole description.
70
+
### Markup tags to use in the Javadoc
53
71
54
-
**...:** everything else that was already in the comment should stay there below the @webBrief tag
72
+
For code-like (i.e. `looking like this`) styling, use `<b></b>` tags. For emphasis (currently rendered as italics) use `<em></em>`.
55
73
56
-
When you are done with your edits to the JavaDoc, commit your changes and follow these steps:
74
+
Javadoc tags such as `@inheritDoc` and `@link` are not currently supported.
57
75
58
-
1. Set up the environment and run the content script following [these instructions](https://github.com/processing/processing-doclet/blob/main/README.md).
76
+
## `/examples`
59
77
60
-
2.[Publish the website](/docs/publish.md)
61
-
62
-
Reminder: If you are adding content to the reference that does not live in the `processing` source code (such as Java keywords and operators), you must manually edit the corresponding json files in `content/references/translations/en`.
78
+
This folder contains all the examples used inside the references. They are organized in the same folder structure as the `translations` folder. These folders contain all the `.pde` and `.png` files necessary for the examples. Each example image should have a size of `800x800px` and should be named after the corresponding example, e.g. the `bezier_0.pde` example has an image named `bezier_0.png`.
63
79
64
80
## Adding examples and examples images for references
65
81
66
82
The examples live inside the `/content/references/examples/` folder. The main processing references are inside the folder `processing` and references for the libraries are in separate folders named as the library. For each reference (both for processing and libraries) there needs to be a folder, named exactly as the corresponding json file without the `.json` part (those files are in `/content/references/translations/en/processing`). The file should contain:
67
83
68
-
-_.pde files_ containing the code for the example. The code for the .pde files could be found either on the reference pages on the current website or in the .xml files [here](https://github.com/processing/processing-docs/tree/master/content/api_en) under the tag `<example>` (each example is under separate tag). Each library has its own folder starting with `LIB_`.
84
+
-_.pde files_ containing the code for the example. (The original code for the .pde files migrated from the old web reference could be found either on the reference pages on the current website or in the .xml files [here](https://github.com/processing/processing-docs/tree/master/content/api_en) under the tag `<example>` (each example is under separate tag). Each library has its own folder starting with `LIB_`.)
69
85
-_.png files_ if examples produce images. Images can be found [here](https://github.com/processing/processing-docs/tree/master/content/api_media). Each example image should have a size of `800x800px`. If the example has an image, then the code used to generate the images needs to be also updated on the corresponding .pde file with the new scales. The .pde and .png file for the same example should be named the same as the reference with the number of the example starting from 0 (e.g. for reference `ammbientLight_` there are `ammbientLight_0.pde` and `ammbientLight_1.pde` and `ammbientLight_0.png` and `ammbientLight_1.png`).
70
86
71
87
For re-scaling the images and updating the examples codes the workflow should be:
@@ -80,5 +96,4 @@ If you want to add a translation, copy the `en` folder, rename it to the languag
80
96
81
97
Translations of the `.pde` example files in the reference should be added next to the english version `.pde` files in `content/references/examples`.
0 commit comments