eessppeelllloo/processing4
1
0
Fork 0
mirror of https://github.com/processing/processing4.git synced 2026-05-09 12:22:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #222 from designsystemsinternational/doclet-changes

Browse Source
This commit is contained in:
Ben Fry
2021-07-06 05:50:14 -04:00
committed by GitHub
parent 5af82c1989 080db98d3d
commit 3898369cc7
37 changed files with 91 additions and 2270 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/src/processing/core/PApplet.java
+57 -57
View File
@@ -2989,7 +2989,7 @@ public class PApplet implements PConstants {
* This is a function, rather than a variable, because it may
* change multiple times per frame.
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the number of milliseconds (thousandths of a second) since
* starting an applet
* @see PApplet#second()
@@ -3009,7 +3009,7 @@ public class PApplet implements PConstants {
* Processing communicates with the clock on your computer. The
* <b>second()</b> function returns the current second as a value from 0 - 59.
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the current second as a value from 0 - 59
* @see PApplet#millis()
* @see PApplet#minute()
@@ -3028,7 +3028,7 @@ public class PApplet implements PConstants {
* <b>minute()</b> function returns the current minute as a value from 0 - 59.
*
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the current minute as a value from 0 - 59
* @see PApplet#millis()
* @see PApplet#second()
@@ -3047,7 +3047,7 @@ public class PApplet implements PConstants {
* Processing communicates with the clock on your computer. The
* <b>hour()</b> function returns the current hour as a value from 0 - 23.
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the current hour as a value from 0 - 23
* @see PApplet#millis()
* @see PApplet#second()
@@ -3073,7 +3073,7 @@ public class PApplet implements PConstants {
* If you're looking for the day of the week (M-F or whatever)
* or day of the year (1..365) then use java's Calendar.get()
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the current day as a value from 1 - 31
* @see PApplet#millis()
* @see PApplet#second()
@@ -3092,7 +3092,7 @@ public class PApplet implements PConstants {
* <b>month()</b> function returns the current month as a value from 1 - 12.
*
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the current month as a value from 1 - 12
* @see PApplet#millis()
* @see PApplet#second()
@@ -3113,7 +3113,7 @@ public class PApplet implements PConstants {
* 2004, 2005, etc).
*
*
* @webref input:time_date
* @webref input:time date
* @webBrief Returns the current year as an integer (2003,
* 2004, 2005, etc)
* @see PApplet#millis()
@@ -3908,7 +3908,7 @@ public class PApplet implements PConstants {
* frames per second). It should also be noted, that a print() within a for loop
* can sometimes lock up the program, and cause the sketch to freeze.
*
* @webref output:text_area
* @webref output:text area
* @webBrief Writes to the console area of the Processing environment
* @usage IDE
* @param what
@@ -3995,7 +3995,7 @@ public class PApplet implements PConstants {
* frames per second). It should also be noted, that a println() within a for
* loop can sometimes lock up the program, and cause the sketch to freeze.
*
* @webref output:text_area
* @webref output:text area
* @webBrief Writes to the text area of the Processing environment's console
* @usage IDE
* @see PApplet#print(byte)
@@ -4101,7 +4101,7 @@ public class PApplet implements PConstants {
* real-time output (such as at 60 frames per second).
*
*
* @webref output:text_area
* @webref output:text area
* @webBrief Writes array data to the text
* area of the Processing environment's console.
* @param what one-dimensional array
@@ -5271,7 +5271,7 @@ public class PApplet implements PConstants {
* interpret the HTML as image data.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Loads an image into a variable of type <b>PImage</b>
* @param filename
* name of file to load, can be .gif, .jpg, .tga, or a handful of
@@ -5326,7 +5326,7 @@ public class PApplet implements PConstants {
* extension as the second parameter to <b>requestImage()</b>.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Loads images on a separate thread so that your sketch does not
* freeze while images load during <b>setup()</b>
* @param filename
@@ -5896,7 +5896,7 @@ public class PApplet implements PConstants {
* many font sizes are needed, or when using any renderer based on the default
* renderer, such as the PDF library.
*
* @webref typography:loading_displaying
* @webref typography:loading & displaying
* @webBrief Loads a font into a variable of type <b>PFont</b>
* @param filename
* name of the font to load
@@ -5961,7 +5961,7 @@ public class PApplet implements PConstants {
* poor when exporting if the sketch does not include the .otf or .ttf file,
* and the requested font is not available on the machine running the sketch.
*
* @webref typography:loading_displaying
* @webref typography:loading & displaying
* @webBrief Dynamically converts a font to the format used by Processing
* @param name
* name of the font to load
@@ -7755,7 +7755,7 @@ public class PApplet implements PConstants {
* sorted. <!--As of release 0126, the alphabetical ordering is case
* insensitive.-->
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Sorts an array of numbers from smallest to largest and puts an
* array of words in alphabetical order
* @param list
@@ -7853,7 +7853,7 @@ public class PApplet implements PConstants {
* "https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#arraycopy-java.lang.Object-int-java.lang.Object-int-int-">System.arraycopy()</a>
* method, so most things that apply there are inherited.
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Copies an array (or part of an array) to another array
* @param src
* the source array
@@ -7934,7 +7934,7 @@ public class PApplet implements PConstants {
* (SomeClass[]) expand(originalArray)</em>
*
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Increases the size of an array
* @param list
* the array to expand
@@ -8055,7 +8055,7 @@ public class PApplet implements PConstants {
* items = (SomeClass[]) append(originalArray, element)</em>.
*
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Expands an array by one element and adds data to the new position
* @param array array to append
* @param value new data for the array
@@ -8109,7 +8109,7 @@ public class PApplet implements PConstants {
* items = (SomeClass[]) shorten(originalArray)</em>.
*
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Decreases an array by one element and returns the shortened array
* @param list array to shorten
* @see PApplet#append(byte[], byte)
@@ -8159,7 +8159,7 @@ public class PApplet implements PConstants {
* be cast to the object array's data type. For example: <em>SomeClass[] items
* = (SomeClass[]) splice(array1, array2, index)</em>
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Inserts a value or array of values into an existing array
* @param list
* array to splice into
@@ -8334,7 +8334,7 @@ public class PApplet implements PConstants {
* cast to the object array's data type. For example: <em>SomeClass[] items =
* (SomeClass[]) subset(originalArray, 0, 4)</em>
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Extracts an array of elements from an existing array
* @param list
* array to extract from
@@ -8460,7 +8460,7 @@ public class PApplet implements PConstants {
* cast to the object array's data type. For example: <em>SomeClass[] items =
* (SomeClass[]) concat(array1, array2)</em>.
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Concatenates two arrays
* @param a
* first array to concatenate
@@ -8529,7 +8529,7 @@ public class PApplet implements PConstants {
*
* Reverses the order of an array.
*
* @webref data:array_functions
* @webref data:array functions
* @webBrief Reverses the order of an array
* @param list booleans[], bytes[], chars[], ints[], floats[], or Strings[]
* @see PApplet#sort(String[], int)
@@ -9817,7 +9817,7 @@ public class PApplet implements PConstants {
* More about how colors are stored can be found in the reference for the
* <a href="color_datatype.html">color</a> datatype.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Creates colors for storing in variables of the <b>color</b>
* datatype
* @param gray
@@ -9948,7 +9948,7 @@ public class PApplet implements PConstants {
* unexpected colors.
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Calculates a <b>color</b> or <b>colors</b> between two <b>colors</b> at a specific
* increment
* @usage web_application
@@ -11465,7 +11465,7 @@ public class PApplet implements PConstants {
* <b>circle()</b> or <b>square()</b>.
*
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a point, a coordinate in space at the dimension of one pixel
* @param x x-coordinate of the point
* @param y y-coordinate of the point
@@ -11498,7 +11498,7 @@ public class PApplet implements PConstants {
* Drawing this shape in 3D with the <b>z</b> parameter requires the P3D
* parameter in combination with <b>size()</b> as shown in the above example.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a line (a direct path between two points) to the screen
* @param x1 x-coordinate of the first point
* @param y1 y-coordinate of the first point
@@ -11532,7 +11532,7 @@ public class PApplet implements PConstants {
* arguments specify the first point, the middle two arguments specify the
* second point, and the last two arguments specify the third point.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief A triangle is a plane created by connecting three points
* @param x1 x-coordinate of the first point
* @param y1 y-coordinate of the first point
@@ -11557,7 +11557,7 @@ public class PApplet implements PConstants {
* vertex and the subsequent pairs should proceed clockwise or
* counter-clockwise around the defined shape.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief A quad is a quadrilateral, a four sided polygon
* @param x1 x-coordinate of the first corner
* @param y1 y-coordinate of the first corner
@@ -11627,7 +11627,7 @@ public class PApplet implements PConstants {
* clockwise around the rectangle.
*
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a rectangle to the screen
* @param a x-coordinate of the rectangle by default
* @param b y-coordinate of the rectangle by default
@@ -11674,7 +11674,7 @@ public class PApplet implements PConstants {
* <b>rectMode()</b> function.
*
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a square to the screen
* @param x x-coordinate of the rectangle by default
* @param y y-coordinate of the rectangle by default
@@ -11733,7 +11733,7 @@ public class PApplet implements PConstants {
* third and fourth parameters set the shape's width and height. The origin may
* be changed with the <b>ellipseMode()</b> function.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws an ellipse (oval) in the display window
* @param a x-coordinate of the ellipse
* @param b y-coordinate of the ellipse
@@ -11767,7 +11767,7 @@ public class PApplet implements PConstants {
* you're having an issue with how arcs are rendered, you'll need to draw the
* arc yourself with <b>beginShape()</b>/<b>endShape()</b> or a <b>PShape</b>.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws an arc in the display window
* @param a x-coordinate of the arc's ellipse
* @param b y-coordinate of the arc's ellipse
@@ -11804,7 +11804,7 @@ public class PApplet implements PConstants {
* and height. The origin may be changed with the <b>ellipseMode()</b>
* function.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a circle to the screen
* @param x x-coordinate of the ellipse
* @param y y-coordinate of the ellipse
@@ -11824,7 +11824,7 @@ public class PApplet implements PConstants {
* is a cube.
*
*
* @webref shape:3d_primitives
* @webref shape:3d primitives
* @webBrief A box is an extruded <b>rectangle</b>
* @param size dimension of the box in all dimensions (creates a cube)
* @see PGraphics#sphere(float)
@@ -11867,7 +11867,7 @@ public class PApplet implements PConstants {
* Code for enhanced u/v version from davbol [080801].
*
* @param res number of segments (minimum 3) used per full circle revolution
* @webref shape:3d_primitives
* @webref shape:3d primitives
* @webBrief Controls the detail used to render a sphere by adjusting the number of
* vertices of the sphere mesh
* @see PGraphics#sphere(float)
@@ -11914,7 +11914,7 @@ public class PApplet implements PConstants {
* [davbol 080801] now using separate sphereDetailU/V
* </PRE>
*
* @webref shape:3d_primitives
* @webref shape:3d primitives
* @webBrief A sphere is a hollow ball made from tessellated triangles
* @param r the radius of the sphere
* @see PGraphics#sphereDetail(int)
@@ -12275,7 +12275,7 @@ public class PApplet implements PConstants {
* case-sensitive language.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Modifies the location from which images draw
* @param mode either CORNER, CORNERS, or CENTER
* @see PApplet#loadImage(String, String)
@@ -12309,7 +12309,7 @@ public class PApplet implements PConstants {
* <h3>Advanced</h3> Starting with release 0124, when using the default (JAVA2D)
* renderer, smooth() will also improve image quality of resized images.
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Displays images to the screen
* @param img the image to display
* @param a x-coordinate of the image by default
@@ -12367,7 +12367,7 @@ public class PApplet implements PConstants {
* Processing is a case sensitive language.
*
*
* @webref shape:loading_displaying
* @webref shape:loading & displaying
* @webBrief Modifies the location from which shapes draw
* @param mode either CORNER, CORNERS, CENTER
* @see PShape
@@ -12398,7 +12398,7 @@ public class PApplet implements PConstants {
* can be used to change the way these parameters are interpreted.
*
*
* @webref shape:loading_displaying
* @webref shape:loading & displaying
* @webBrief Displays shapes to the screen
* @param shape the shape to display
* @param x x-coordinate of the shape
@@ -12526,7 +12526,7 @@ public class PApplet implements PConstants {
* <br />
*
*
* @webref typography:loading_displaying
* @webref typography:loading & displaying
* @webBrief Sets the current font that will be drawn with the <b>text()</b>
* function
* @param which any variable of the type PFont
@@ -12687,7 +12687,7 @@ public class PApplet implements PConstants {
* be used instead. (See the third example above.)
*
*
* @webref typography:loading_displaying
* @webref typography:loading & displaying
* @webBrief Draws text to the screen
* @param c the alphanumeric character to be displayed
* @param x x-coordinate of text
@@ -14081,7 +14081,7 @@ public class PApplet implements PConstants {
* displaying images with their original hues.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Removes the current fill value for displaying images and reverts to
* displaying images with their original hues
* @usage web_application
@@ -14120,7 +14120,7 @@ public class PApplet implements PConstants {
* in 3D.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Sets the fill value for displaying images
* @usage web_application
* @param rgb color value in hexadecimal notation
@@ -14285,7 +14285,7 @@ public class PApplet implements PConstants {
* and <b>shininess()</b> in setting the material properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the ambient reflectance for shapes drawn to the screen
* @usage web_application
* @param rgb any value of the color datatype
@@ -14328,7 +14328,7 @@ public class PApplet implements PConstants {
* setting the material properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the specular color of the materials used for shapes drawn to the
* screen, which sets the color of highlights
* @usage web_application
@@ -14373,7 +14373,7 @@ public class PApplet implements PConstants {
* setting the material properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the amount of gloss in the surface of shapes
* @usage web_application
* @param shine degree of shininess
@@ -14395,7 +14395,7 @@ public class PApplet implements PConstants {
* properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the emissive color of the material used for drawing shapes drawn to
* the screen
* @usage web_application
@@ -14896,7 +14896,7 @@ public class PApplet implements PConstants {
*
* Extracts the alpha value from a color.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the alpha value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -14932,7 +14932,7 @@ public class PApplet implements PConstants {
* </pre>
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the red value from a color, scaled to match current
* <b>colorMode()</b>
* @usage web_application
@@ -14970,7 +14970,7 @@ public class PApplet implements PConstants {
* </pre>
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the green value from a color, scaled to match current
* <b>colorMode()</b>
* @usage web_application
@@ -15008,7 +15008,7 @@ public class PApplet implements PConstants {
* </pre>
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the blue value from a color, scaled to match current
* <b>colorMode()</b>
* @usage web_application
@@ -15030,7 +15030,7 @@ public class PApplet implements PConstants {
*
* Extracts the hue value from a color.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the hue value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -15050,7 +15050,7 @@ public class PApplet implements PConstants {
*
* Extracts the saturation value from a color.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the saturation value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -15071,7 +15071,7 @@ public class PApplet implements PConstants {
* Extracts the brightness value from a color.
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the brightness value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -15307,7 +15307,7 @@ public class PApplet implements PConstants {
* which will make the image into a "correct" grayscale by
* performing a proper luminance-based conversion.
*
* @webref pimage:method
* @webref image:pixels
* @webBrief Masks part of an image with another image as an alpha channel
* @usage web_application
* @param img image to use as the mask
core/src/processing/core/PGraphics.java
+32 -32
View File
@@ -2520,7 +2520,7 @@ public class PGraphics extends PImage implements PConstants {
* <b>circle()</b> or <b>square()</b>.
*
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a point, a coordinate in space at the dimension of one pixel
* @param x x-coordinate of the point
* @param y y-coordinate of the point
@@ -2553,7 +2553,7 @@ public class PGraphics extends PImage implements PConstants {
* Drawing this shape in 3D with the <b>z</b> parameter requires the P3D
* parameter in combination with <b>size()</b> as shown in the above example.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a line (a direct path between two points) to the screen
* @param x1 x-coordinate of the first point
* @param y1 y-coordinate of the first point
@@ -2589,7 +2589,7 @@ public class PGraphics extends PImage implements PConstants {
* arguments specify the first point, the middle two arguments specify the
* second point, and the last two arguments specify the third point.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief A triangle is a plane created by connecting three points
* @param x1 x-coordinate of the first point
* @param y1 y-coordinate of the first point
@@ -2617,7 +2617,7 @@ public class PGraphics extends PImage implements PConstants {
* vertex and the subsequent pairs should proceed clockwise or
* counter-clockwise around the defined shape.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief A quad is a quadrilateral, a four sided polygon
* @param x1 x-coordinate of the first corner
* @param y1 y-coordinate of the first corner
@@ -2695,7 +2695,7 @@ public class PGraphics extends PImage implements PConstants {
* clockwise around the rectangle.
*
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a rectangle to the screen
* @param a x-coordinate of the rectangle by default
* @param b y-coordinate of the rectangle by default
@@ -2860,7 +2860,7 @@ public class PGraphics extends PImage implements PConstants {
* <b>rectMode()</b> function.
*
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a square to the screen
* @param x x-coordinate of the rectangle by default
* @param y y-coordinate of the rectangle by default
@@ -2923,7 +2923,7 @@ public class PGraphics extends PImage implements PConstants {
* third and fourth parameters set the shape's width and height. The origin may
* be changed with the <b>ellipseMode()</b> function.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws an ellipse (oval) in the display window
* @param a x-coordinate of the ellipse
* @param b y-coordinate of the ellipse
@@ -2990,7 +2990,7 @@ public class PGraphics extends PImage implements PConstants {
* you're having an issue with how arcs are rendered, you'll need to draw the
* arc yourself with <b>beginShape()</b>/<b>endShape()</b> or a <b>PShape</b>.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws an arc in the display window
* @param a x-coordinate of the arc's ellipse
* @param b y-coordinate of the arc's ellipse
@@ -3076,7 +3076,7 @@ public class PGraphics extends PImage implements PConstants {
* and height. The origin may be changed with the <b>ellipseMode()</b>
* function.
*
* @webref shape:2d_primitives
* @webref shape:2d primitives
* @webBrief Draws a circle to the screen
* @param x x-coordinate of the ellipse
* @param y y-coordinate of the ellipse
@@ -3099,7 +3099,7 @@ public class PGraphics extends PImage implements PConstants {
* is a cube.
*
*
* @webref shape:3d_primitives
* @webref shape:3d primitives
* @webBrief A box is an extruded <b>rectangle</b>
* @param size dimension of the box in all dimensions (creates a cube)
* @see PGraphics#sphere(float)
@@ -3196,7 +3196,7 @@ public class PGraphics extends PImage implements PConstants {
* Code for enhanced u/v version from davbol [080801].
*
* @param res number of segments (minimum 3) used per full circle revolution
* @webref shape:3d_primitives
* @webref shape:3d primitives
* @webBrief Controls the detail used to render a sphere by adjusting the number of
* vertices of the sphere mesh
* @see PGraphics#sphere(float)
@@ -3278,7 +3278,7 @@ public class PGraphics extends PImage implements PConstants {
* [davbol 080801] now using separate sphereDetailU/V
* </PRE>
*
* @webref shape:3d_primitives
* @webref shape:3d primitives
* @webBrief A sphere is a hollow ball made from tessellated triangles
* @param r the radius of the sphere
* @see PGraphics#sphereDetail(int)
@@ -3893,7 +3893,7 @@ public class PGraphics extends PImage implements PConstants {
* case-sensitive language.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Modifies the location from which images draw
* @param mode either CORNER, CORNERS, or CENTER
* @see PApplet#loadImage(String, String)
@@ -3932,7 +3932,7 @@ public class PGraphics extends PImage implements PConstants {
* <h3>Advanced</h3> Starting with release 0124, when using the default (JAVA2D)
* renderer, smooth() will also improve image quality of resized images.
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Displays images to the screen
* @param img the image to display
* @param a x-coordinate of the image by default
@@ -4105,7 +4105,7 @@ public class PGraphics extends PImage implements PConstants {
* Processing is a case sensitive language.
*
*
* @webref shape:loading_displaying
* @webref shape:loading & displaying
* @webBrief Modifies the location from which shapes draw
* @param mode either CORNER, CORNERS, CENTER
* @see PShape
@@ -4149,7 +4149,7 @@ public class PGraphics extends PImage implements PConstants {
* can be used to change the way these parameters are interpreted.
*
*
* @webref shape:loading_displaying
* @webref shape:loading & displaying
* @webBrief Displays shapes to the screen
* @param shape the shape to display
* @param x x-coordinate of the shape
@@ -4401,7 +4401,7 @@ public class PGraphics extends PImage implements PConstants {
* <br />
*
*
* @webref typography:loading_displaying
* @webref typography:loading & displaying
* @webBrief Sets the current font that will be drawn with the <b>text()</b>
* function
* @param which any variable of the type PFont
@@ -4719,7 +4719,7 @@ public class PGraphics extends PImage implements PConstants {
* be used instead. (See the third example above.)
*
*
* @webref typography:loading_displaying
* @webref typography:loading & displaying
* @webBrief Draws text to the screen
* @param c the alphanumeric character to be displayed
* @param x x-coordinate of text
@@ -6734,7 +6734,7 @@ public class PGraphics extends PImage implements PConstants {
* displaying images with their original hues.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Removes the current fill value for displaying images and reverts to
* displaying images with their original hues
* @usage web_application
@@ -6772,7 +6772,7 @@ public class PGraphics extends PImage implements PConstants {
* in 3D.
*
*
* @webref image:loading_displaying
* @webref image:loading & displaying
* @webBrief Sets the fill value for displaying images
* @usage web_application
* @param rgb color value in hexadecimal notation
@@ -6975,7 +6975,7 @@ public class PGraphics extends PImage implements PConstants {
* and <b>shininess()</b> in setting the material properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the ambient reflectance for shapes drawn to the screen
* @usage web_application
* @param rgb any value of the color datatype
@@ -7031,7 +7031,7 @@ public class PGraphics extends PImage implements PConstants {
* setting the material properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the specular color of the materials used for shapes drawn to the
* screen, which sets the color of highlights
* @usage web_application
@@ -7091,7 +7091,7 @@ public class PGraphics extends PImage implements PConstants {
* setting the material properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the amount of gloss in the surface of shapes
* @usage web_application
* @param shine degree of shininess
@@ -7111,7 +7111,7 @@ public class PGraphics extends PImage implements PConstants {
* properties of shapes.
*
*
* @webref lights_camera:material_properties
* @webref lights_camera:material properties
* @webBrief Sets the emissive color of the material used for drawing shapes drawn to
* the screen
* @usage web_application
@@ -7998,7 +7998,7 @@ public class PGraphics extends PImage implements PConstants {
*
* Extracts the alpha value from a color.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the alpha value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -8036,7 +8036,7 @@ public class PGraphics extends PImage implements PConstants {
* </pre>
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the red value from a color, scaled to match current
* <b>colorMode()</b>
* @usage web_application
@@ -8076,7 +8076,7 @@ public class PGraphics extends PImage implements PConstants {
* </pre>
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the green value from a color, scaled to match current
* <b>colorMode()</b>
* @usage web_application
@@ -8116,7 +8116,7 @@ public class PGraphics extends PImage implements PConstants {
* </pre>
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the blue value from a color, scaled to match current
* <b>colorMode()</b>
* @usage web_application
@@ -8140,7 +8140,7 @@ public class PGraphics extends PImage implements PConstants {
*
* Extracts the hue value from a color.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the hue value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -8165,7 +8165,7 @@ public class PGraphics extends PImage implements PConstants {
*
* Extracts the saturation value from a color.
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the saturation value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -8191,7 +8191,7 @@ public class PGraphics extends PImage implements PConstants {
* Extracts the brightness value from a color.
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Extracts the brightness value from a color
* @usage web_application
* @param rgb any value of the color datatype
@@ -8232,7 +8232,7 @@ public class PGraphics extends PImage implements PConstants {
* unexpected colors.
*
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Calculates a <b>color</b> or <b>colors</b> between two <b>colors</b> at a specific
* increment
* @usage web_application
core/src/processing/core/PImage.java
+2 -2
View File
@@ -842,7 +842,7 @@ public class PImage implements PConstants, Cloneable {
* which will make the image into a "correct" grayscale by
* performing a proper luminance-based conversion.
*
* @webref pimage:method
* @webref image:pixels
* @webBrief Masks part of an image with another image as an alpha channel
* @usage web_application
* @param img image to use as the mask
@@ -1599,7 +1599,7 @@ public class PImage implements PConstants, Cloneable {
* are preferable, and the difference is insignificant for applications
* built with Processing.</P>
*
* @webref color:creating_reading
* @webref color:creating & reading
* @webBrief Blends two color values together based on the blending mode given as the
* <b>MODE</b> parameter
* @usage web_application
doclet/README.md
-33
View File
@@ -1,33 +0,0 @@
# Doclet
This is a custom Doclet that generates JSON files based on Javadoc comments in `.java` files. These JSON files have all the information necessary for building the reference pages on [processing.org](https://processing.org).
The Doclet will run through the `.java` file in the following repositories:
- [`processing/processing4`](https://github.com/processing/processing4) (this repo)
- [`processing/processing-sound`](https://github.com/processing/processing-sound)
- [`processing/processing-video`](https://github.com/processing/processing-video)
It will read the JavaDoc comments, create a series of `.json` files, and save them into the Processing website repository in the `content/references/translations/en/` folder:
- [`processing/processing-website`](https://github.com/processing/processing-website)
## How to use
First, make sure that you have the proper setup before running the script:
- Clone down whichever repository listed above that you need to have updated on the website. You will need at least one of `processing/processing4`, `processing/processing-sound` or `processing/processing-video` alongside the `processing/processing-website` repo. The repositories need to be alongside each other in the same folder.
- Make sure you have Java JDK 11 installed and the `JAVA_HOME` environment variable set to point to the installation. The name of the JDK file may vary depending on your exact version (e.g. `export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.8.jdk/Contents/Home/`).
- Make sure you have [Apache Ant](https://ant.apache.org/manual/install.html) installed in version 1.8 or above.
Now you are ready to run the doclet
1. First `cd` into the `processing4/doclet/ReferenceGenerator` folder
2. Run `ant compile`
3. Run `./processingrefBuild.sh` if you are updating all the repositories or `./processingrefBuild.sh processing`, `./processingrefBuild.sh sound` or `./processingrefBuild.sh video` if you are updating a single repository.
If you just want to test the Doclet without the `processing-website` repo, you can create the following folder structure in the root folder and see the files:
```
processing-website/content/references/translations/en/
```
doclet/ReferenceGenerator/.classpath
-9
View File
@@ -1,9 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="src"/>
<classpathentry kind="src" path="Tools"/>
<classpathentry exported="true" kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
<classpathentry exported="true" kind="lib" path="lib/org.json.jar"/>
<classpathentry kind="lib" path="Tools/tools.jar"/>
<classpathentry kind="output" path="bin"/>
</classpath>
doclet/ReferenceGenerator/.profile
-3
View File
@@ -1,3 +0,0 @@
JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_202.jdk/Contents/Home/
export JAVA_HOME;
doclet/ReferenceGenerator/.project
-24
View File
@@ -1,24 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
<name>ReferenceGenerator</name>
<comment></comment>
<projects>
</projects>
<buildSpec>
<buildCommand>
<name>org.eclipse.jdt.core.javabuilder</name>
<arguments>
</arguments>
</buildCommand>
</buildSpec>
<natures>
<nature>org.eclipse.jdt.core.javanature</nature>
</natures>
<linkedResources>
<link>
<name>Tools</name>
<type>2</type>
<location>/Library/Java/JavaVirtualMachines/jdk1.8.0_202.jdk/Contents/Home/lib</location>
</link>
</linkedResources>
</projectDescription>
doclet/ReferenceGenerator/.settings/org.eclipse.jdt.core.prefs
-12
View File
@@ -1,12 +0,0 @@
#Wed Sep 12 09:51:20 EDT 2012
eclipse.preferences.version=1
org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled
org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.6
org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve
org.eclipse.jdt.core.compiler.compliance=1.6
org.eclipse.jdt.core.compiler.debug.lineNumber=generate
org.eclipse.jdt.core.compiler.debug.localVariable=generate
org.eclipse.jdt.core.compiler.debug.sourceFile=generate
org.eclipse.jdt.core.compiler.problem.assertIdentifier=error
org.eclipse.jdt.core.compiler.problem.enumIdentifier=error
org.eclipse.jdt.core.compiler.source=1.6
doclet/ReferenceGenerator/androidrefBuild.sh
-32
View File
@@ -1,32 +0,0 @@
#!/bin/sh
#remove everything old
rm -rf ../tmp
#generate everything anew
javadoc -doclet ProcessingWeblet -docletpath bin/ -public \
-webref ../tmp/web-android \
-localref ../tmp/local-android \
-includeXMLTag android \
-templatedir ../templates \
-examplesdir ../api_examples \
-includedir ../api_examples/include \
-imagedir images \
-corepackage processing.xml \
-rootclass PGraphics \
-rootclass PConstants \
../../../processing/android/core/src/processing/android/core/*.java \
../../../processing/android/core/src/processing/android/xml/*.java \
../../../processing/net/src/processing/net/*.java \
../../../processing/serial/src/processing/serial/*.java
# ../../../processing/video/src/processing/video/*.java \
#copy over the css and sample images
cp -r ../../css ../tmp/web-android
cp -r ../../css ../tmp/local-android
mkdir ../tmp/web-android/images
mkdir ../tmp/local-android/images
cp -r ../../content/api_media/*.jpg ../tmp/web-android/images/
cp -r ../../content/api_media/*.gif ../tmp/web-android/images/
cp -r ../../content/api_media/*.png ../tmp/web-android/images/
cp -r ../../content/api_media/*.jpg ../tmp/local-android/images/
cp -r ../../content/api_media/*.gif ../tmp/local-android/images/
cp -r ../../content/api_media/*.png ../tmp/local-android/images/
doclet/ReferenceGenerator/bin/ProcessingWeblet.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/BaseWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/ClassWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/FieldWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/FileUtils.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/FunctionWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/LibraryWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/MethodWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/Shared.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/bin/writers/TemplateWriter.class
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/build.xml
-65
View File
@@ -1,65 +0,0 @@
<project name="Procesing Web Reference Generator" default="compile" basedir=".">
<description>
Build file for the Processing documentation generator.
Creates the ProcessingWeblet.class, which is used by javadoc to structure
the parsed Processing source code into the website reference.
</description>
<!-- set global properties for this build -->
<property name="src" location="src"/>
<property name="build" location="bin"/>
<property name="test" location="test"/>
<target name="init">
<!-- Create the time stamp -->
<tstamp/>
<!-- Create the build directory structure used by compile -->
<mkdir dir="${build}"/>
</target>
<path id="class.path">
<fileset dir="lib">
<include name="*.jar" />
</fileset>
</path>
<target name="rundoc">
<mkdir dir="docs" />
<javadoc access="public" destdir="docs">
<fileset dir="test" defaultexcludes="yes">
<include name="*" />
</fileset>
<classpath refid="class.path" />
<doclet name="ProcessingWeblet" path="bin">
<param name="-webref" value="../../reference"/>
<param name="-localref" value="../../distribution"/>
<param name="-templatedir" value="../templates"/>
<param name="-examplesdir" value="../../content/api_en"/>
<param name="-includedir" value="../../content/api_en/include"/>
<param name="-imagedir" value="images"/>
<param name="-encoding" value="UTF-8"/>
<param name="-corepackage" value="processing.data"/>
<param name="-corepackage" value="processing.event"/>
<param name="-corepackage" value="processing.opengl"/>
<param name="-rootclass" value="PConstants"/>
</doclet>
</javadoc>
</target>
<target name="compile" depends="clean,init"
description="compile the source " >
<!-- Compile the java code from ${src} into ${build} -->
<!-- Note that your environment JAVA_HOME now matters for building -->
<javac srcdir="${src}" destdir="${build}" source="11" target="11" includeantruntime="true">
<classpath refid="class.path" />
</javac>
</target>
<target name="clean"
description="clean up" >
<!-- Delete the ${build} and ${dist} directory trees -->
<delete dir="${build}"/>
</target>
</project>
doclet/ReferenceGenerator/lib/org.json.jar
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/lib/tools.jar
BIN
View File
Binary file not shown.
doclet/ReferenceGenerator/processingrefBuild.sh
-59
View File
@@ -1,59 +0,0 @@
#!/bin/sh
echo "[REFERENCE GENERATOR] Booting up..."
# PROCESSING_SRC_PATH=./test
PROCESSING_SRC_PATH=../../core/src
PROCESSING_LIB_PATH=../../java/libraries
REFERENCES_OUT_PATH=../../../processing-website/content/references/translations/en
# GENERATE REFERENCE ENTRIES AND INDEX THROUGH JAVADOC - BY DAVID WICKS
echo "[REFERENCE GENERATOR] Source Path :: $PROCESSING_SRC_PATH"
echo "[REFERENCE GENERATOR] Library Path :: $PROCESSING_LIB_PATH"
# You can pass one argument "sound" or "video" to generate those libraries separately
# or "processing" to generate the core without the sound and video libraries
# if there is no argument it will generate everything
if [ $# -eq 0 ]
then
echo "No arguments supplied, generating everything"
echo "[REFERENCE GENERATOR] Removing previous version of the ref..."
FOLDERS="$PROCESSING_SRC_PATH/processing/core/*.java \
$PROCESSING_SRC_PATH/processing/data/*.java \
$PROCESSING_SRC_PATH/processing/event/*.java \
$PROCESSING_SRC_PATH/processing/opengl/*.java \
$PROCESSING_LIB_PATH/io/src/processing/io/*.java \
$PROCESSING_LIB_PATH/net/src/processing/net/*.java \
$PROCESSING_LIB_PATH/serial/src/processing/serial/*.java \
$PROCESSING_LIB_PATH/../../../processing-video/src/processing/video/*.java \
$PROCESSING_LIB_PATH/../../../processing-sound/src/processing/sound/*.java"
elif [ $1 = "processing" ]
then
echo "Generating processing references"
echo "[REFERENCE GENERATOR] Removing previous version of the ref..."
FOLDERS="$PROCESSING_SRC_PATH/processing/core/*.java \
$PROCESSING_SRC_PATH/processing/data/*.java \
$PROCESSING_SRC_PATH/processing/event/*.java \
$PROCESSING_SRC_PATH/processing/opengl/*.java \
$PROCESSING_LIB_PATH/io/src/processing/io/*.java \
$PROCESSING_LIB_PATH/net/src/processing/net/*.java \
$PROCESSING_LIB_PATH/serial/src/processing/serial/*.java"
else
echo "Generating $1 library"
echo "[REFERENCE GENERATOR] Removing previous version of the ref..."
FOLDERS="$PROCESSING_LIB_PATH/../../../processing-$1/src/processing/$1/*.java"
fi
echo "[REFERENCE GENERATOR] Generating new javadocs..."
javadoc -doclet ProcessingWeblet \
-docletpath "bin/:lib/org.json.jar" \
-public \
-webref ../../reference \
-localref ../../distribution \
-templatedir ../templates \
-examplesdir ../../content/api_en \
-includedir ../../content/api_en/include \
-imagedir images \
-encoding UTF-8 \
$FOLDERS \
-noisy
doclet/ReferenceGenerator/src/ProcessingWeblet.java
-151
View File
@@ -1,151 +0,0 @@
import java.io.IOException;
import writers.ClassWriter;
import writers.FieldWriter;
import writers.FunctionWriter;
import writers.LibraryWriter;
import writers.Shared;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Tag;
import com.sun.tools.doclets.standard.Standard;
import org.json.*;
/*
* @author David Wicks
* ProcessingWeblet generates the web reference for processing.org and download
* The source code of processing is parsed for webref tags to determine what gets included
* Flags for javadoc when running include:
* -templatedir where to find the html templates for output
* -examplesdir where to find the xml describing the examples to go in the reference
* -localref the local reference output directory
* -webref the web reference output directory
* -corepackage pass in as many of these as necessary to have things considered as part of the core (not a library) e.g -corepackage processing.xml
* -includedir where to find things that aren't in the source, but only in xml e.g. [] (arrayaccess)
*/
public class ProcessingWeblet extends Standard {
private static String examplesFlag = "-examplesdir";
private static String templateFlag = "-templatedir";
private static String outputFlag = "-webref";
private static String exceptionsFlag = "-includedir";
private static String imagesFlag = "-imagedir";
private static String localFlag = "-localref";
private static String coreFlag = "-corepackage"; //to allow for exceptions like XML being in the core
private static String verboseFlag = "-noisy";
private static String rootFlag = "-rootclass";
private static String xmlDescriptionFlag = "-includeXMLTag";
public static boolean start(RootDoc root)
{
setConfig(root.options());
Shared.i().createBaseDirectories();
try
{
// write out everything in the .java files:
// Classes, Methods, Fields ... see specific XxxWriters
System.out.println("\n===Writing .javadoc sourced reference.===");
writeContents(root);
System.out.println("===Source code @webref files written.===");
} catch (IOException e) {
// TODO Auto-generated catch block
e.printStackTrace();
}
System.out.println("===All finished in the weblet.===");
return true;
}
private static void setConfig(String[][] configOptions) {
//
Shared.i().corePackages.add("processing.core");
Shared.i().rootClasses.add("PApplet");
Shared.i().rootClasses.add("PConstants");
// look at all possible options (this .equals thing kills switch statements...or does it?)
for (String[] option : configOptions) {
if (option[0].equals(templateFlag)) {
Shared.i().setTemplateDirectory(option[1]);
} else if (option[0].equals(examplesFlag)) {
Shared.i().setExampleDirectory(option[1]);
} else if (option[0].equals(outputFlag)) {
Shared.i().setOutputDirectory(option[1]);
} else if (option[0].equals(exceptionsFlag)) {
// write out files based on exceptions index
Shared.i().setIncludeDirectory( option[1] );
} else if (option[0].equals(imagesFlag)) {
Shared.i().setImageDirectory(option[1]);
} else if( option[0].equals(localFlag) )
{
Shared.i().setLocalOutputDirectory(option[1]);
} else if( option[0].equals(coreFlag)){
Shared.i().corePackages.add(option[1]);
} else if(option[0].equals(verboseFlag)){
Shared.i().setNoisy(true);
} else if( option[0].equals(rootFlag)){
Shared.i().rootClasses.add(option[1]);
} else if( option[0].equals(xmlDescriptionFlag) ) {
Shared.i().addDescriptionTag( option[1] );
}
}
}
public static int optionLength(String option) {
if (option.equals(templateFlag) || option.equals(examplesFlag)
|| option.equals(outputFlag) || option.equals(rootFlag)
|| option.equals(exceptionsFlag) || option.equals(imagesFlag)
|| option.equals(localFlag) || option.equals(coreFlag)
|| option.equals(xmlDescriptionFlag)) {
return 2;
} else if ( option.equals(verboseFlag) ){
return 1;
}
return 0;
}
private static void writeContents(RootDoc root) throws IOException {
System.out.println("Write contents: ");
for( ClassDoc classDoc : root.classes() ){
if(Shared.i().isCore(classDoc)){
// Document the core functions and classes
if(Shared.i().isRootLevel(classDoc)){
//if it is in PApplet, PConstants or other classes where users can get
//the variables without using dot syntax
// document functions
MethodDoc[] functions = classDoc.methods();
for (MethodDoc fn : functions) {
// write out html reference
FunctionWriter.write(fn);
}
//also need to add fields
for(FieldDoc doc : classDoc.fields()){
if(Shared.i().isWebref(doc)){
FieldWriter.write(doc);
}
}
} else {
// document a class and its public properties
new ClassWriter().write( classDoc );
}
} else {
// Document the library passed in
if(Shared.i().isNoisy()) {
System.out.println("Loaded class: " + classDoc.name());
}
LibraryWriter writer = new LibraryWriter();
writer.write(classDoc.containingPackage());
}
}
}
}
doclet/ReferenceGenerator/src/writers/BaseWriter.java
-646
View File
@@ -1,646 +0,0 @@
package writers;
import java.io.BufferedWriter;
import java.io.File;
import java.io.FileWriter;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Calendar;
import java.util.HashMap;
import java.util.Locale;
import java.util.TimeZone;
import org.w3c.dom.Document;
import org.w3c.dom.NodeList;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.Doc;
import com.sun.javadoc.ExecutableMemberDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.ParamTag;
import com.sun.javadoc.Parameter;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.SeeTag;
import com.sun.javadoc.Tag;
import org.json.*;
public class BaseWriter {
// Some utilities
public final static String MODE_JAVASCRIPT = "js";
public final static String jsonDir = "../../../processing-website/content/references/translations/en/processing/";
public BaseWriter()
{
}
protected static BufferedWriter makeWriter(String anchor) throws IOException
{
return makeWriter(anchor, false);
}
protected static String getWriterPath( String anchor, Boolean isLocal )
{
if (!isLocal) {
return Shared.i().getOutputDirectory() + "/" + anchor;
} else
{
return Shared.i().getLocalOutputDirectory() + anchor;
}
}
protected static BufferedWriter makeWriter(String anchor, Boolean isLocal) throws IOException {
FileWriter fw = new FileWriter( getWriterPath( anchor, isLocal ) );
return new BufferedWriter(fw);
}
protected static String getAnchor(ProgramElementDoc doc)
{
String ret = getAnchorFromName(getName(doc));
if(doc.containingClass() != null && !Shared.i().isRootLevel(doc.containingClass()))
{
ret = doc.containingClass().name() + "_" + ret;
}
if(!Shared.i().isCore(doc)){
//add package name to anchor
String[] parts = doc.containingPackage().name().split("\\.");
String pkg = parts[parts.length-1] + "/";
if (pkg.equals("data/") || pkg.equals("opengl/"))
ret = ret;
else
ret = pkg + ret;
}
return ret;
}
protected static String getLocalAnchor(ProgramElementDoc doc)
{
String ret = getAnchorFromName(getName(doc));
if(doc.containingClass() != null){
ret = doc.containingClass().name() + "_" + ret;
}
return ret;
}
protected static String getReturnTypes(MethodDoc doc)
{
String ret = nameInPDE(doc.returnType().toString());
if(doc.containingClass() != null)
{
for(MethodDoc m : doc.containingClass().methods())
{
if( m.name().equals(doc.name()) && m.returnType() != doc.returnType() )
{
String name = getSimplifiedType( nameInPDE(m.returnType().toString()) );
if( ! ret.contains( name ) )
{ // add return type name if it's not already included
ret += ", " + name;
}
}
}
}
// add "or" (split first to make sure we don't mess up the written description)
ret = ret.replaceFirst( ",([^,]+)$", ", or$1" );
if( ! ret.matches(".+,.+,.+") )
{
ret = ret.replace( ",", "" );
}
return ret;
}
protected static String getSimplifiedType( String str )
{
if( str.equals("long") ){ return "int"; }
if( str.equals("double") ){ return "float"; }
return str;
}
protected static String getName(Doc doc) { // handle
String ret = doc.name();
if(doc instanceof MethodDoc)
{
ret = ret.concat("()");
} else if (doc.isField()){
// add [] if needed
FieldDoc d = (FieldDoc) doc;
ret = ret.concat(d.type().dimension());
}
return ret;
}
protected static String getAnchorFromName(String name){
// change functionName() to functionName_
if( name.endsWith("()") ){
name = name.replace("()", "_");
}
// change "(some thing)" to something
if( name.contains("(") && name.contains(")") ){
int start = name.lastIndexOf("(") + 1;
int end = name.lastIndexOf(")");
name = name.substring(start, end);
name = name.replace(" ", "");
}
// change thing[] to thing
if( name.contains("[]")){
name = name.replaceAll("\\[\\]", "");
}
// change "some thing" to "some_thing.html"
name = name.replace(" ", "_");
return name;
}
static protected String getBasicDescriptionFromSource(ProgramElementDoc doc) {
return getBasicDescriptionFromSource(longestText(doc));
}
static protected String getBriefDescriptionFromSource(ProgramElementDoc doc) {
Tag[] sta = doc.tags("brief");
if(sta.length > 0){
return sta[0].text();
}
return getBasicDescriptionFromSource(doc);
}
static protected String getWebDescriptionFromSource(ProgramElementDoc doc) {
Tag[] sta = doc.tags("webDescription");
if(sta.length > 0){
return sta[0].text();
}
return getBasicDescriptionFromSource(doc);
}
static protected String getWebBriefFromSource(ProgramElementDoc doc) {
Tag[] sta = doc.tags("webBrief");
if(sta.length > 0){
return sta[0].text();
}
return getBasicDescriptionFromSource(doc);
}
static protected String longestText(ProgramElementDoc doc){
if(Shared.i().isWebref(doc)){
//override longest rule if the element has an @webref tag
return doc.commentText();
}
String s = doc.commentText();
if( doc.isMethod() ){
for(ProgramElementDoc d : doc.containingClass().methods()){
if(d.name().equals(doc.name() ) ){
if(d.commentText().length() > s.length()){
s = d.commentText();
}
}
}
} else if(doc.isField()){
for(ProgramElementDoc d : doc.containingClass().fields()){
if(d.name().equals(doc.name() ) ){
if(d.commentText().length() > s.length()){
s = d.commentText();
}
}
}
}
return s;
}
static protected String getBasicDescriptionFromSource(String s){
String[] sa = s.split("(?i)(<h\\d>Advanced:?</h\\d>)|(=advanced)");
if (sa.length != 0)
s = sa[0];
return s;
}
static protected String getAdvancedDescriptionFromSource(ProgramElementDoc doc) {
return getAdvancedDescriptionFromString(longestText(doc));
}
static private String getAdvancedDescriptionFromString(String s) {
String[] sa = s.split("(?i)(<h\\d>Advanced:?</h\\d>)|(=advanced)");
if (sa.length > 1)
s = sa[1];
return s;
}
protected static HashMap<String, String> getDefaultDescriptionVars ()
{
HashMap<String, String> vars = new HashMap<String, String>();
vars.put("description title", "Description");
vars.put("description text", "");
return vars;
}
protected static String getTimestamp() {
Calendar now = Calendar.getInstance();
Locale us = new Locale("en");
return now.getDisplayName(Calendar.MONTH, Calendar.LONG, us)
+ " "
+ now.get(Calendar.DAY_OF_MONTH)
+ ", "
+ now.get(Calendar.YEAR)
+ " "
+ FileUtils.nf(now.get(Calendar.HOUR), 2)
+ ":"
+ FileUtils.nf(now.get(Calendar.MINUTE), 2)
+ ":"
+ FileUtils.nf(now.get(Calendar.SECOND), 2)
+ now.getDisplayName(Calendar.AM_PM, Calendar.SHORT, us)
.toLowerCase()
+ " "
+ TimeZone.getDefault().getDisplayName(
TimeZone.getDefault().inDaylightTime(now.getTime()),
TimeZone.SHORT, us);
}
/*
* Get all the syntax possibilities for a method
*/
protected static ArrayList<HashMap<String, String>> getSyntax(MethodDoc doc, String instanceName) throws IOException
{
TemplateWriter templateWriter = new TemplateWriter();
ArrayList<HashMap<String, String>> ret = new ArrayList<HashMap<String,String>>();
for( MethodDoc methodDoc : doc.containingClass().methods() )
{
if(Shared.i().shouldOmit(methodDoc)){
continue;
}
if( methodDoc.name().equals(doc.name() ))
{
HashMap<String, String> map = new HashMap<String, String>();
map.put("name", methodDoc.name());
map.put("object", instanceName);
ArrayList<HashMap<String, String>> parameters = new ArrayList<HashMap<String,String>>();
String params="";
for( Parameter p : methodDoc.parameters() )
{
params = params + p.name() + ", ";
HashMap<String, String> paramMap = new HashMap<String, String>();
paramMap.put("parameter", p.name());
parameters.add(paramMap);
}
if(params.endsWith(", ")){
params = params.substring(0, params.lastIndexOf(", "));
}
map.put("parameters", params);
if( ! ret.contains(map) )
{
//don't put in duplicate function syntax
ret.add(map);
}
}
}
return ret;
}
private static String removePackage(String name)
{ // keep everything after the last dot
if( name.contains(".") )
{ return name.substring( name.lastIndexOf(".") + 1 ); }
return name;
}
private static String nameInPDE(String fullName)
{
if( fullName.contains("<") && fullName.endsWith(">") )
{ // if this type uses Java generics
String parts[] = fullName.split("<");
String generic = removePackage( parts[0] );
String specialization = removePackage( parts[1] );
specialization = specialization.substring( 0, specialization.length() - 1 );
return generic + "&lt;" + specialization + "&gt;";
}
return removePackage( fullName );
}
protected static String getUsage(ProgramElementDoc doc){
Tag[] tags = doc.tags("usage");
if(tags.length != 0){
return tags[0].text();
}
tags = doc.containingClass().tags("usage");
if(tags.length != 0){
return tags[0].text();
}
// return empty string if no usage is found
return "";
}
protected static String getInstanceName(ProgramElementDoc doc){
Tag[] tags = doc.containingClass().tags("instanceName");
if(tags.length != 0){
return tags[0].text().split("\\s")[0];
}
return "";
}
protected static String getInstanceDescription(ProgramElementDoc doc){
Tag[] tags = doc.containingClass().tags("instanceName");
if(tags.length != 0){
String s = tags[0].text();
return s.substring(s.indexOf(" "));
}
return "";
}
protected static ArrayList<JSONObject> getParameters(MethodDoc doc) throws IOException{
//get parent
ClassDoc cd = doc.containingClass();
ArrayList<JSONObject> ret = new ArrayList<JSONObject>();
if(!Shared.i().isRootLevel(cd)){
//add the parent parameter if this isn't a function of PApplet
JSONObject parent = new JSONObject();
try
{
ArrayList<String> paramType = new ArrayList<String>();
paramType.add(cd.name());
parent.put("name", getInstanceName(doc));
parent.put("type", paramType);
parent.put("description",getInstanceDescription(doc));
ret.add(parent);
} catch (JSONException ex)
{
ex.printStackTrace();
}
}
//get parameters from this and all other declarations of method
for( MethodDoc m : cd.methods() ){
if(Shared.i().shouldOmit(m)){
continue;
}
if(m.name().equals(doc.name())){
ret.addAll(parseParameters(m));
}
}
removeDuplicateParameters(ret);
return ret;
}
protected static ArrayList<JSONObject> getParameters(ClassDoc doc) throws IOException{
ArrayList<JSONObject> ret = new ArrayList<JSONObject>();
for( ConstructorDoc m : doc.constructors() ){
if(Shared.i().shouldOmit(m)){
continue;
}
ret.addAll(parseParameters(m));
}
removeDuplicateParameters(ret);
return ret;
}
protected static void removeDuplicateParameters(ArrayList<JSONObject> ret){
// combine duplicate parameter names with differing types
try
{
for(JSONObject parameter : ret)
{
String desc = parameter.getString("description");
JSONArray paramArray = parameter.getJSONArray("type");
if(!desc.endsWith(": "))
{
// if the chosen description has actual text
// e.g. float: something about the float
for(JSONObject parameter2 : ret)
{
String desc2 = parameter2.getString("description");
if(parameter2.getString("name").equals( parameter.getString("name") ) )
{
// freshen up our variable with the latest description
// for (int i=0; i < parameter2.get("type").size(); i++) {
// System.out.println("par " + parameter2.get("type").get(i));
// }
JSONArray paramArray2 = parameter2.getJSONArray("type");
String addItem = "";
for(int i = 0; i < paramArray.length(); i++)
{
for(int j = 0; j < paramArray2.length(); j++) {
if ( !paramArray.getString(i).equals(paramArray2.getString(j))) {
addItem = paramArray2.getString(j);
}
}
}
if (addItem != "") {
paramArray.put(addItem);
}
}
}
}
ArrayList<String> newList = new ArrayList<String>();
for (int i = 0; i < paramArray.length(); i++) {
if (!newList.contains(paramArray.getString(i))) {
newList.add(paramArray.getString(i));
}
}
parameter.put("type", newList);
}
//remove parameters without descriptions
for( int i=ret.size()-1; i >= 0; i-- )
{
if(ret.get(i).getString("description").equals(""))
{
ret.remove(i);
}
}
} catch (JSONException ex)
{
ex.printStackTrace();
}
}
protected static ArrayList<JSONObject> parseParameters(ExecutableMemberDoc doc){
ArrayList<JSONObject> paramList = new ArrayList<JSONObject>();
for( Parameter param : doc.parameters()){
String type = getSimplifiedType( nameInPDE(param.type().toString()) );
String name = param.name();
String desc = "";
for( ParamTag tag : doc.paramTags() ){
if(tag.parameterName().equals(name)){
desc = desc.concat( tag.parameterComment() );
}
}
JSONObject paramJSON = new JSONObject();
try
{
ArrayList<String> paramType = new ArrayList<String>();
paramType.add(type);
paramJSON.put("name", name);
paramJSON.put("type", paramType);
paramJSON.put("description", desc);
} catch (JSONException ex)
{
ex.printStackTrace();
}
paramList.add(paramJSON);
}
return paramList;
}
protected static ArrayList<SeeTag> getAllSeeTags( ProgramElementDoc doc )
{
ArrayList<SeeTag> ret = new ArrayList<SeeTag>();
ClassDoc cd = doc.containingClass();
if( cd != null && doc.isMethod() )
{ // if there is a containing class, get @see tags for all
// methods with the same name as this one
// Fixes gh issue 293
for( MethodDoc m : cd.methods() )
{
if(m.name().equals(doc.name()))
{
for( SeeTag tag : m.seeTags() )
{
ret.add( tag );
}
}
}
}
else
{ // if no containing class (e.g. doc is a class)
// just grab the see tags in the class doc comment
for( SeeTag tag : doc.seeTags() )
{
ret.add( tag );
}
}
return ret;
}
protected static ArrayList<String> getRelated( ProgramElementDoc doc ) throws IOException
{
TemplateWriter templateWriter = new TemplateWriter();
ArrayList<HashMap<String, String>> vars = new ArrayList<HashMap<String,String>>();
ArrayList<String> related = new ArrayList<String>();
// keep track of class members so that links to methods in e.g. PGraphics
// that are copied into PApplet are correctly linked.
HashMap<String, ProgramElementDoc> classMethods = new HashMap<String, ProgramElementDoc>();
HashMap<String, ProgramElementDoc> classFields = new HashMap<String, ProgramElementDoc>();
if( doc.isMethod() || doc.isField() )
{ // fill our maps
ClassDoc containingClass = doc.containingClass();
for( MethodDoc m : containingClass.methods() ) {
if( needsWriting( m ) ) {
classMethods.put( m.name(), m );
}
}
for( FieldDoc f : containingClass.fields() ) {
if( needsWriting( f ) ) {
classFields.put( f.name(), f );
}
}
}
// add link to each @see item
for( SeeTag tag : getAllSeeTags( doc ) )
{
HashMap<String, String> map = new HashMap<String, String>();
ProgramElementDoc ref = tag.referencedClass();
if( tag.referencedMember() != null )
{
ref = tag.referencedMember();
if( ref.isMethod() && classMethods.containsKey( ref.name() ) ) {
// link to the member as it is in this class, instead of
// as it is in another class
ProgramElementDoc prior = classMethods.get( ref.name() );
ref = prior;
}
else if ( ref.isField() && classFields.containsKey( ref.name() ) ) {
ProgramElementDoc prior = classFields.get( ref.name() );
ref = prior;
}
}
if( needsWriting( ref ) )
{ // add links to things that are actually written
map.put("anchor", getAnchor( ref ));
related.add(getAnchor(ref));
}
}
// add link to each @see_external item
for( Tag tag : doc.tags( Shared.i().getSeeAlsoTagName() ) )
{
related.add( tag.text().concat("_") );
}
return related;
}
protected static String getEvents(ProgramElementDoc doc){
return "";
}
/**
* Modes should support all API, so if XML not explicitly states "not supported", then assume it does.
*/
protected static boolean isModeSupported ( ProgramElementDoc doc, String mode ) {
return true;
}
protected static boolean needsWriting(ProgramElementDoc doc){
if( (doc != null) && Shared.i().isWebref(doc) )
{
return true;
}
return false;
}
public static String getCategory(Tag webref){
String firstPart = webref.text().split("\\s")[0];
String[] parts = firstPart.split(":");
if( parts.length > 1 ){
return parts[0];
}
return firstPart;
}
public static String getSubcategory(Tag webref){
String firstPart = webref.text().split("\\s")[0];
String[] parts = firstPart.split(":");
if( parts.length > 1 ){
return parts[1];
}
return "";
}
}
doclet/ReferenceGenerator/src/writers/ClassWriter.java
-164
View File
@@ -1,164 +0,0 @@
package writers;
import java.io.*;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.Parameter;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.Tag;
import org.json.*;
public class ClassWriter extends BaseWriter {
private ClassDoc classDoc;
private String libDir;
public ClassWriter() {
}
@SuppressWarnings("unchecked")
public void write( ClassDoc classDoc ) throws IOException {
if( needsWriting(classDoc) )
{
TemplateWriter templateWriter = new TemplateWriter();
this.classDoc = classDoc;
String classname = getName(classDoc);
String anchor = getAnchor(classDoc);
HashMap<String, String> vars = new HashMap<String, String>();
JSONObject classJSON = new JSONObject();
String fileName, folderName;
if (libDir != null) {
fileName = libDir + classname + ".json";
folderName = libDir;
}
else {
fileName = jsonDir + classname + ".json";
folderName = jsonDir;
}
Tag[] tags = classDoc.tags(Shared.i().getWebrefTagName());
String category = getCategory(tags[0]);
String subcategory = getSubcategory(tags[0]);
try
{
classJSON.put("type", "class");
// These vars will be inherited by method and field writers
classJSON.put("name", classname);
classJSON.put("classanchor", anchor);
String desc = getWebDescriptionFromSource(classDoc);
if ( desc != "" )
{
classJSON.put( "description", desc );
}
if( !Shared.i().isCore(classDoc))
{ // documenting a library
classJSON.put("isLibrary", "true" );
classJSON.put("csspath", "../../");
}
classJSON.put("brief", getWebBriefFromSource(classDoc));
ArrayList<JSONObject> methodSet = new ArrayList<JSONObject>();
ArrayList<JSONObject> fieldSet = new ArrayList<JSONObject>();
// Write all @webref methods for core classes (the tag tells us where to link to it in the index)
for (MethodDoc m : classDoc.methods()) {
if(needsWriting(m)){
if (!classname.equals("PGraphics") || getName(m).equals("beginDraw()") || getName(m).equals("endDraw()")) {
MethodWriter.write((HashMap<String, String>)vars.clone(), m, classname, folderName);
methodSet.add(getPropertyInfo(m));
}
}
}
for (FieldDoc f : classDoc.fields()) {
if(needsWriting(f)){
FieldWriter.write((HashMap<String, String>)vars.clone(), f, classname);
fieldSet.add(getPropertyInfo(f));
}
}
ArrayList<String> constructors = getConstructors();
classJSON.put("category", category);
classJSON.put("subcategory", subcategory);
classJSON.put("methods", methodSet);
classJSON.put("classFields", fieldSet);
classJSON.put("constructors", constructors);
classJSON.put("parameters", getParameters(classDoc));
classJSON.put("related", getRelated(classDoc));
} catch (JSONException ex)
{
ex.printStackTrace();
}
try {
FileWriter file = new FileWriter(fileName);
file.write(classJSON.toString());
file.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
public void write( ClassDoc classDoc, String lib ) throws IOException {
libDir = lib;
write(classDoc);
}
private ArrayList<String> getConstructors()
{
ArrayList<String> constructors = new ArrayList<String>();
for( ConstructorDoc c : classDoc.constructors() )
{
if(Shared.i().shouldOmit(c)){
continue;
}
String constructor = c.name() + "(";
for( Parameter p : c.parameters() )
{
constructor += p.name() + ", ";
}
if( constructor.endsWith(", ") )
{
constructor = constructor.substring(0, constructor.length()-2) + ")";
}
else {
constructor += ")";
}
constructors.add(constructor);
}
return constructors;
}
private JSONObject getPropertyInfo(ProgramElementDoc doc) {
JSONObject ret = new JSONObject();
try
{
ret.put("name", getName(doc));
ret.put("anchor", getLocalAnchor(doc));
ret.put("desc", getWebBriefFromSource(doc));
} catch (JSONException ex)
{
ex.printStackTrace();
}
return ret;
}
}
doclet/ReferenceGenerator/src/writers/FieldWriter.java
-120
View File
@@ -1,120 +0,0 @@
package writers;
import java.io.IOException;
import java.util.HashMap;
import java.util.ArrayList;
import java.io.*;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.Tag;
import org.json.*;
public class FieldWriter extends BaseWriter {
/**
*
* @param vars inherited from containing ClassDoc
* @param doc
* @throws IOException
*/
public static void write(HashMap<String, String> vars, FieldDoc doc, String classname) throws IOException
{
TemplateWriter templateWriter = new TemplateWriter();
JSONObject fieldJSON = new JSONObject();
String fieldName;
if (getName(doc).contains("[]")) {
fieldName = getName(doc).replace("[]", "");
} else {
fieldName = getName(doc);
}
String fileName;
if (classname != "") {
fileName = jsonDir + classname + "_" + fieldName + ".json";
} else {
fileName = jsonDir + fieldName + ".json";
}
Tag[] tags = doc.tags(Shared.i().getWebrefTagName());
String category = getCategory(tags[0]);
String subcategory = getSubcategory(tags[0]);
try
{
fieldJSON.put("description", getWebDescriptionFromSource(doc));
fieldJSON.put("brief", getWebBriefFromSource(doc));
fieldJSON.put("category", category);
fieldJSON.put("subcategory", subcategory);
fieldJSON.put("name", getName(doc));
fieldJSON.put("related", getRelated(doc));
if(Shared.i().isRootLevel(doc.containingClass())){
fieldJSON.put("type", "other");
} else {
fieldJSON.put("type", "field");
fieldJSON.put("classanchor", getLocalAnchor(doc.containingClass()));
fieldJSON.put("parameters", getParentParam(doc));
String syntax = templateWriter.writePartial("field.syntax.partial", getSyntax(doc));
ArrayList<String> syntaxList = new ArrayList<String>();
syntaxList.add(syntax);
fieldJSON.put("syntax", syntaxList);
}
} catch (JSONException ex)
{
ex.printStackTrace();
}
try {
FileWriter file = new FileWriter(fileName);
file.write(fieldJSON.toString());
file.close();
} catch (IOException e) {
e.printStackTrace();
}
}
public static void write(FieldDoc doc) throws IOException
{
String classname = "";
write(new HashMap<String, String>(), doc, classname);
}
protected static HashMap<String, String> getSyntax(FieldDoc doc){
HashMap<String, String> map = new HashMap<String, String>();
map.put("object", getInstanceName(doc));
map.put("field", getName(doc));
return map;
}
protected static ArrayList<JSONObject> getParentParam(FieldDoc doc){
ArrayList<JSONObject> retList = new ArrayList<JSONObject>();
JSONObject ret = new JSONObject();
try
{
ret.put("name", getInstanceName(doc));
ret.put("desc", getInstanceDescription(doc));
} catch (JSONException ex)
{
ex.printStackTrace();
}
retList.add(ret);
return retList;
}
protected static HashMap<String, String> getParent(FieldDoc doc){
HashMap<String, String> parent = new HashMap<String, String>();
ClassDoc cd = doc.containingClass();
parent.put("name", getInstanceName(doc));
parent.put("name", getInstanceName(doc));
parent.put("type", cd.name());
parent.put("description", getInstanceDescription(doc));
return parent;
}
}
doclet/ReferenceGenerator/src/writers/FileUtils.java
-78
View File
@@ -1,78 +0,0 @@
package writers;
import java.io.BufferedReader;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.text.NumberFormat;
//taken from processing source, yay
public class FileUtils {
static public String nf(int num, int digits) {
NumberFormat int_nf;
int_nf = NumberFormat.getInstance();
int_nf.setGroupingUsed(false); // no commas
int_nf.setMinimumIntegerDigits(digits);
return int_nf.format(num);
}
static public String[] loadStrings(String filename){
InputStream is = createInput(filename);
if (is != null) return loadStrings(is);
return null;
}
static public InputStream createInput(String filename) {
File file = new File(filename);
try {
return new FileInputStream(file);
} catch (FileNotFoundException e) {
// TODO Auto-generated catch block
e.printStackTrace();
return null;
}
}
static public String[] loadStrings(InputStream input) {
try {
BufferedReader reader =
new BufferedReader(new InputStreamReader(input, "UTF-8"));
String lines[] = new String[100];
int lineCount = 0;
String line = null;
while ((line = reader.readLine()) != null) {
if (lineCount == lines.length) {
String temp[] = new String[lineCount << 1];
System.arraycopy(lines, 0, temp, 0, lineCount);
lines = temp;
}
lines[lineCount++] = line;
}
reader.close();
if (lineCount == lines.length) {
return lines;
}
// resize array to appropriate amount for these lines
String output[] = new String[lineCount];
System.arraycopy(lines, 0, output, 0, lineCount);
return output;
} catch (IOException e) {
e.printStackTrace();
//throw new RuntimeException("Error inside loadStrings()");
}
return null;
}
}
doclet/ReferenceGenerator/src/writers/FunctionWriter.java
-62
View File
@@ -1,62 +0,0 @@
package writers;
import java.io.*;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.Tag;
import org.json.*;
public class FunctionWriter extends BaseWriter {
static ArrayList<String> writtenFunctions;
public FunctionWriter(){}
public static void write(MethodDoc doc) throws IOException
{
if( needsWriting(doc)){
String anchor = getAnchor(doc);
TemplateWriter templateWriter = new TemplateWriter();
ArrayList<String> syntax = templateWriter.writeLoopSyntax("function.syntax.partial", getSyntax(doc, ""));
JSONObject functionJSON = new JSONObject();
String fileName = jsonDir + getName(doc).replace("()", "_") + ".json";
Tag[] tags = doc.tags(Shared.i().getWebrefTagName());
String category = getCategory(tags[0]);
String subcategory = getSubcategory(tags[0]);
try
{
functionJSON.put("type", "function");
functionJSON.put("name", getName(doc));
functionJSON.put("description", getWebDescriptionFromSource(doc));
functionJSON.put("brief", getWebBriefFromSource(doc));
functionJSON.put("category", category);
functionJSON.put("subcategory", subcategory);
functionJSON.put("syntax", syntax);
functionJSON.put("parameters", getParameters(doc));
functionJSON.put("related", getRelated(doc));
functionJSON.put("returns", getReturnTypes(doc));
} catch (JSONException ex)
{
ex.printStackTrace();
}
try {
FileWriter file = new FileWriter(fileName);
file.write(functionJSON.toString());
file.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
doclet/ReferenceGenerator/src/writers/LibraryWriter.java
-64
View File
@@ -1,64 +0,0 @@
package writers;
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.PackageDoc;
public class LibraryWriter extends BaseWriter {
PackageDoc doc;
String pkg;
String dir;
static TemplateWriter templateWriter;
static ArrayList<String> writtenLibraries;
private String libDir ="../../../processing-website/content/references/translations/en/";
public LibraryWriter(){
if(templateWriter == null ){
templateWriter = new TemplateWriter();
}
if(writtenLibraries == null){
writtenLibraries = new ArrayList<String>();
}
}
public void write(PackageDoc doc)
{
// check for files that haven't been read
if(writtenLibraries.contains(doc.name())){
return;
}
writtenLibraries.add(doc.name());
String[] parts = doc.name().split("\\.");
String pkg = parts[parts.length-1] + "/";
if (pkg.equals("data/") || pkg.equals("opengl/"))
dir = jsonDir;
else
dir = libDir + pkg;
Shared.i().createOutputDirectory(dir);
//grab all relevant information for the doc
for( ClassDoc classDoc : doc.allClasses() ){
// document the class if it has a @webref tag
try
{
new ClassWriter().write(classDoc, dir);
} catch (IOException e)
{
// TODO Auto-generated catch block
e.printStackTrace();
}
}
}
}
doclet/ReferenceGenerator/src/writers/MethodWriter.java
-81
View File
@@ -1,81 +0,0 @@
package writers;
import java.io.IOException;
import java.util.HashMap;
import java.util.ArrayList;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.Tag;
import java.io.*;
import org.json.*;
public class MethodWriter extends BaseWriter {
public MethodWriter(){}
/**
*
*
* @param vars the inherited vars from the method's ClassDoc
* @param doc the method doc
* @throws IOException
*/
public static void write( HashMap<String, String> vars, MethodDoc doc, String classname, String foldername) throws IOException
{
String filename = getAnchor(doc);
TemplateWriter templateWriter = new TemplateWriter();
ArrayList<String> syntax = templateWriter.writeLoopSyntax("method.syntax.partial", getSyntax(doc, getInstanceName(doc)));
JSONObject methodJSON = new JSONObject();
String fileName = foldername + classname + "_" + getName(doc).replace("()", "_") + ".json";
Tag[] tags = doc.tags(Shared.i().getWebrefTagName());
String category = getCategory(tags[0]);
String subcategory = getSubcategory(tags[0]);
if (!classname.equals("PGraphics") || getName(doc).equals("beginDraw()") || getName(doc).equals("endDraw()")) {
try
{
methodJSON.put("type", "method");
methodJSON.put("name", getName(doc));
methodJSON.put("description", getWebDescriptionFromSource(doc));
methodJSON.put("brief", getWebBriefFromSource(doc));
methodJSON.put("category", category);
methodJSON.put("subcategory", subcategory);
methodJSON.put("syntax", syntax);
methodJSON.put("parameters", getParameters(doc));
methodJSON.put("related", getRelated(doc));
methodJSON.put("returns", getReturnTypes(doc));
} catch (JSONException ex)
{
ex.printStackTrace();
}
try
{
if(Shared.i().isRootLevel(doc.containingClass())){
methodJSON.put("classname", "");
} else {
methodJSON.put("classanchor", getLocalAnchor(doc.containingClass()));
}
} catch (JSONException ex)
{
ex.printStackTrace();
}
try {
FileWriter file = new FileWriter(fileName);
file.write(methodJSON.toString());
file.close();
} catch (IOException e) {
e.printStackTrace();
}
}
}
}
doclet/ReferenceGenerator/src/writers/Shared.java
-201
View File
@@ -1,201 +0,0 @@
package writers;
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import org.w3c.dom.Document;
import com.sun.javadoc.Doc;
import com.sun.javadoc.ProgramElementDoc;
public class Shared {
// what we're looking for
private static Shared instance;
private String webrefTagName = "webref";
private String seeAlsoTagName = "see_external";
private String coreClassName = "PApplet";
private ArrayList<String> descriptionSets;
//where things go
private String outputDirectory = "web_reference";
private String localOutputDirectory = "local_reference";
private String imageDirectory = "images";
private String fileExtension = ".html";
//where things come from
private String templateDirectory = "templates";
private String exampleDirectory = "web_examples";
private String includeDirectory = "include";
private String jsonDirectory ="../../../processing-website/content/references/translations/en/processing/";
boolean noisy = false;
public ArrayList<String> corePackages;
public ArrayList<String> rootClasses;
private Shared(){
corePackages = new ArrayList<String>();
rootClasses = new ArrayList<String>();
descriptionSets = new ArrayList<String>();
addDescriptionTag("description");
}
public static Shared i()
{
if(instance == null)
{
instance = new Shared();
}
return instance;
}
public String getWebrefTagName(){
return webrefTagName;
}
public String getSeeAlsoTagName()
{
return seeAlsoTagName;
}
public void setIncludeDirectory( String s )
{
includeDirectory = s;
}
public String getIncludeDirectory()
{
return includeDirectory + "/";
}
public void setWebrefTagName(String webrefTagName)
{
this.webrefTagName = webrefTagName;
}
public void setCoreClassName(String coreClassName)
{
this.coreClassName = coreClassName;
}
public String getCoreClassName()
{
return coreClassName;
}
public void addDescriptionTag(String s) {
System.out.println( "Added description tag: " + s );
descriptionSets.add( "/root/"+s );
descriptionSets.add( "/root/js_mode/"+s );
}
public ArrayList<String> getDescriptionSets() {
return descriptionSets;
}
public void setOutputDirectory(String outputDirectory) {
this.outputDirectory = outputDirectory;
}
public String getOutputDirectory() {
return outputDirectory;
}
public void setFileExtension(String fileExtension) {
this.fileExtension = fileExtension;
}
public String getFileExtension() {
return fileExtension;
}
public void setTemplateDirectory(String templateDirectory) {
this.templateDirectory = templateDirectory;
}
public String getTemplateDirectory() {
return templateDirectory;
}
public String TEMPLATE_DIRECTORY(){
return templateDirectory + "/";
}
public void setExampleDirectory(String exampleDirectory) {
this.exampleDirectory = exampleDirectory;
}
public String getExampleDirectory() {
return exampleDirectory;
}
public String getJSONDirectory(){
return jsonDirectory + "/";
}
public void setImageDirectory(String imageDirectory) {
this.imageDirectory = imageDirectory;
}
public String getImageDirectory(){
return imageDirectory + "/";
}
public void setLocalOutputDirectory(String localOutputDirectory) {
this.localOutputDirectory = localOutputDirectory;
}
public String getLocalOutputDirectory()
{
return localOutputDirectory + "/";
}
public String OUTPUT_DIRECTORY()
{
return outputDirectory + "/";
}
public boolean isCore(ProgramElementDoc doc){
return corePackages.contains(doc.containingPackage().name());
}
public boolean isWebref(ProgramElementDoc doc){
return doc.tags(webrefTagName).length > 0;
}
public boolean isRootLevel(ProgramElementDoc doc){
if(doc.isClass() || doc.isInterface()){
return rootClasses.contains(doc.name());
} else {
return rootClasses.contains(doc.containingClass().name());
}
}
public boolean isNoisy(){
return noisy;
}
public void setNoisy(boolean b){
noisy = b;
}
public void createOutputDirectory(String dir){
System.out.println("Creating output directory: " + dir );
File f = new File(getLocalOutputDirectory() + dir);
f.mkdirs();
f = new File(OUTPUT_DIRECTORY() + dir);
f.mkdirs();
}
public void createBaseDirectories(){
File f = new File(getLocalOutputDirectory());
f.mkdirs();
f = new File(OUTPUT_DIRECTORY());
f.mkdirs();
}
public boolean shouldOmit(Doc doc){
if( doc.tags("nowebref").length > 0 )
{
return true;
}
if( doc.tags("notWebref").length > 0 )
{
return true;
}
// if none found, we should include
return false;
}
}
doclet/ReferenceGenerator/src/writers/TemplateWriter.java
-239
View File
@@ -1,239 +0,0 @@
package writers;
import java.io.BufferedWriter;
import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.HashMap;
public class TemplateWriter extends BaseWriter {
public static String varPrefix = "<!-- ";
public static String varSuffix = " -->";
static String[] genericFields = {"classname", "returns", "related", "parameters", "syntax", "webcontentpath"};
static String[] navFields = {"isLibrary", "isAlphabetical", "isLanguage"};
public TemplateWriter()
{
}
public void write( String templateName, HashMap<String, String> vars, String outputName ) throws IOException
{
for(String s : genericFields){
if( ! vars.containsKey(s)){
vars.put(s, "");
}
}
int unsetNavCount = 0;
for(String s : navFields){
if(!vars.containsKey(s)){
vars.put(s, "");
unsetNavCount++;
}else if(!vars.get(s).equals("")){
vars.put(s, "class='active'");
}
}
if(unsetNavCount == navFields.length){
vars.put("isLanguage", "class='active'");
}
Boolean written = write( templateName, vars, outputName, false );
write( templateName, vars, outputName, true );
if( written && Shared.i().isNoisy() )
{
System.out.println("Wrote " + outputName + " from template");
}
}
// returns a relative path to root (e.g. "../../" from "path/to/File.ext", or "" for "File.txt")
public String getRelativePathToRoot( String path )
{
String[] parts = path.split("/");
String ret = "";
for( int i = parts.length - 1; i > 0; --i )
{
ret += "../";
}
return ret;
}
private Boolean write( String templateName, HashMap<String, String> vars, String outputName, Boolean isLocal ) throws IOException
{
String[] templateFile = FileUtils.loadStrings(Shared.i().TEMPLATE_DIRECTORY() + templateName);
ArrayList<String> output = new ArrayList<String>();
vars.put("timestamp", getTimestamp());
if(isLocal)
{
vars.put( "webcontentpath", getRelativePathToRoot( outputName ) );
vars.put("jquery", writePartial("jquery.local.partial.html", vars));
vars.put("navigation", writePartial("nav.local.template.html", vars));
} else
{
vars.put( "webcontentpath", "/" );
vars.put("jquery", writePartial("jquery.web.partial.html", vars));
vars.put("navigation", writePartial("nav.web.template.html", vars));
}
File f = new File( getWriterPath( outputName, isLocal ) );
if( ! f.exists() )
{
BufferedWriter out = makeWriter(outputName, isLocal);
for( String line : templateFile )
{
// check if it contains a variable we want to replace, then replace it
line = writeLine(line, vars, false);
output.add(line);
}
for( String line : output )
{
out.write(line+"\n");
}
out.close();
return true;
}
else
{
return false;
}
}
public String writePartial( String templateName, HashMap<String, String> vars )
{ //use to write partials to be assigned to vars keys
String[] templateFile = FileUtils.loadStrings(Shared.i().TEMPLATE_DIRECTORY()+templateName);
String ret = "";
for( String line : templateFile )
{
line = writeLine(line, vars, false );
ret = ret.concat(line+"\n");
}
return ret;
}
public String writeLoop( String templateName, ArrayList<HashMap<String, String>> varSet )
{
return writeLoop(templateName, varSet, "\n");
}
public String writeLoop( String templateName, ArrayList<HashMap<String, String>> varSet, String separator )
{
String[] templateFile = FileUtils.loadStrings(Shared.i().TEMPLATE_DIRECTORY()+templateName);
String ret = "";
int index = 0;
for( HashMap<String, String> vars : varSet )
{
index++;
for( String line : templateFile )
{
ret = ret + writeLine(line, vars, (index == varSet.size()) ) + separator;
}
}
if(ret.endsWith(separator)){
ret = ret.substring(0, ret.lastIndexOf(separator));
}
return ret;
}
public ArrayList<String> writeLoopSyntax(String templateName, ArrayList<HashMap<String, String>> varSet)
{
String[] templateFile = FileUtils.loadStrings(Shared.i().TEMPLATE_DIRECTORY()+templateName);
ArrayList<String> syntaxList = new ArrayList<String>();
int index = 0;
for( HashMap<String, String> vars : varSet )
{
index++;
for( String line : templateFile )
{
syntaxList.add(writeLine(line, vars, (index == varSet.size()) ));
}
}
return syntaxList;
}
public ArrayList<String> writeFields(String templateName, ArrayList<HashMap<String, String>> varSet)
{
String[] templateFile = FileUtils.loadStrings(Shared.i().TEMPLATE_DIRECTORY()+templateName);
ArrayList<String> syntaxList = new ArrayList<String>();
int index = 0;
for( HashMap<String, String> vars : varSet )
{
index++;
for( String line : templateFile )
{
syntaxList.add(writeLine(line, vars, (index == varSet.size()) ));
}
}
return syntaxList;
}
private String writeLine(String line, HashMap<String, String> map, boolean isFinalLine )
{
for( String key : map.keySet())
{
if(line.contains(key))
{
String value = map.get(key);
value = value.replace("$", "\\$");
// what variable in html the value should replace
String var = varPrefix + key + varSuffix;
// place our value into the html
line = line.replaceFirst(var, value);
// find html that requires presence or lack of value
String requireStart = varPrefix + "require:" + key + varSuffix;
String requireEnd = varPrefix + "end" + varSuffix;
String requireAbsenceStart = varPrefix + "unless:" + key + varSuffix;
String unlessLastStart = varPrefix + "unless:last_fragment" + varSuffix;
if(value.equals(""))
{ //remove html around things that are absent (like images)
while(line.contains(requireStart))
{
String sub = line.substring(line.indexOf(requireStart), line.indexOf(requireEnd) + requireEnd.length());
line = line.replace(sub, "");
}
}
else
{
// remove things that should only exist in absence of this value
while(line.contains(requireAbsenceStart))
{
String sub = line.substring(line.indexOf(requireAbsenceStart), line.indexOf(requireEnd) + requireEnd.length());
line = line.replace(sub, "");
}
}
if( isFinalLine )
{
while(line.contains(unlessLastStart))
{
String sub = line.substring(line.indexOf(unlessLastStart), line.indexOf(requireEnd) + requireEnd.length());
line = line.replace(sub, "");
}
}
// finally, remove all the meta junk
line = line.replaceAll(requireStart, "");
line = line.replaceAll(requireEnd, "");
line = line.replaceAll(requireAbsenceStart, "");
line = line.replaceAll(unlessLastStart, "");
}
}
// Strip trailing whitespace (trim() removes beginning and end)
return line.replaceAll("\\s+$", "");
}
}
doclet/ReferenceGenerator/test/seetags.java
-133
View File
@@ -1,133 +0,0 @@
/* -*- mode: java; c-basic-offset: 2; indent-tabs-mode: nil -*- */
/*
Part of the Processing project - http://processing.org
Copyright (c) 2012-13 The Processing Foundation
Copyright (c) 2004-12 Ben Fry and Casey Reas
Copyright (c) 2001-04 Massachusetts Institute of Technology
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation, version 2.1.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General
Public License along with this library; if not, write to the
Free Software Foundation, Inc., 59 Temple Place, Suite 330,
Boston, MA 02111-1307 USA
*/
package processing.core;
import processing.data.*;
import processing.event.*;
import processing.event.Event;
import processing.opengl.*;
import java.applet.*;
import java.awt.*;
import java.awt.event.ComponentAdapter;
import java.awt.event.ComponentEvent;
import java.awt.event.FocusEvent;
import java.awt.event.FocusListener;
import java.awt.event.InputEvent;
import java.awt.event.KeyListener;
import java.awt.event.MouseAdapter;
import java.awt.event.MouseListener;
import java.awt.event.MouseMotionListener;
import java.awt.event.MouseWheelEvent;
import java.awt.event.MouseWheelListener;
import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;
import java.awt.image.*;
import java.io.*;
import java.lang.reflect.*;
import java.net.*;
import java.text.*;
import java.util.*;
import java.util.regex.*;
import java.util.zip.*;
import javax.imageio.ImageIO;
import javax.swing.JFrame;
import javax.swing.JFileChooser;
import javax.swing.filechooser.FileSystemView;
/**
* Stripped-down "source" for testing reference generator
* @usage Web &amp; Application
*/
public class PApplet extends Applet
implements PConstants, Runnable,
MouseListener, MouseWheelListener, MouseMotionListener, KeyListener, FocusListener
{
/**
* ( begin auto-generated from mousePressed.xml )
*
* The <b>mousePressed()</b> function is called once after every time a
* mouse button is pressed. The <b>mouseButton</b> variable (see the
* related reference entry) can be used to determine which button has been pressed.
*
* ( end auto-generated )
* <h3>Advanced</h3>
*
* If you must, use
* int button = mouseEvent.getButton();
* to figure out which button was clicked. It will be one of:
* MouseEvent.BUTTON1, MouseEvent.BUTTON2, MouseEvent.BUTTON3
* Note, however, that this is completely inconsistent across
* platforms.
* @webref input:mouse
* @webDescription The <b>mousePressed()</b> function is called once after every time a
* mouse button is pressed. The <b>mouseButton</b> variable (see the
* related reference entry) can be used to determine which button has been pressed.
* @webExample examples1
*/
public void mousePressed() { }
public void mousePressed(MouseEvent event) {
mousePressed();
}
/**
* ( begin auto-generated from mouseDragged.xml )
*
* The <b>mouseDragged()</b> function is called once every time the mouse
* moves and a mouse button is pressed.
*
* ( end auto-generated )
* @webref input:mouse
* @webDescription test
* @webExample examples/example2.js
* @see PApplet#mousePressed
* @see PApplet#mousePressed()
*/
public void mouseDragged() { }
public void mouseDragged(MouseEvent event) {
mouseDragged();
}
/**
* ( begin auto-generated from mousePressed_var.xml )
*
* Variable storing if a mouse button is pressed. The value of the system
* variable <b>mousePressed</b> is true if a mouse button is pressed and
* false if a button is not pressed.
*
* ( end auto-generated )
* @webref input:mouse
* @webDescription test
* @webExample examples/example2.js
*/
public boolean mousePressed;
}
doclet/templates/field.syntax.partial
-1
View File
@@ -1 +0,0 @@
<!-- object -->.<!-- field -->
doclet/templates/function.syntax.partial
-1
View File
@@ -1 +0,0 @@
<!-- name -->(<!-- parameters -->)
doclet/templates/method.syntax.partial
-1
View File
@@ -1 +0,0 @@
<!-- object -->.<!-- name -->(<!-- parameters -->)