generate tables instead of manual entry

- make descriptions of table entries phrases instead of sentences;
lower case start, no ending period (not enforced, yet)

- add #Line markup to move one line descriptions to the #Method
body. Later, will generate tables like Member_Functions from this

- add #In markup to associate a #Method with a #Subtopic. Later, will
generate tables of related methods from this

- remove return type from operator overloads in tables

- add new colorTypes to examples that index into arrays of strings
to name them


Docs-Preview: https://skia.org/?cl=100422
TBR=caryclark@google.com
Bug: skia:6898
Change-Id: I8558048866369f419f1944832b99c05da3fd52bb
Reviewed-on: https://skia-review.googlesource.com/100422
Reviewed-by: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@skia.org>

1 files changed, 46 insertions, 0 deletions

diff --git a/docs/SkImage_Reference.bmh b/docs/SkImage_Reference.bmh
index a0e29c2ff5..755478a7c1 100644
--- a/docs/SkImage_Reference.bmh
+++ b/docs/SkImage_Reference.bmh
@@ -144,6 +144,7 @@ drawing.
 
 #Method static sk_sp<SkImage> MakeRasterCopy(const SkPixmap& pixmap)
 
+#Line # Creates Image from Pixmap and copied pixels. ##
 Creates Image from Pixmap and copy of pixels. Since pixels are copied, Pixmap
 pixels may be modified or deleted without affecting Image.
 
@@ -189,6 +190,7 @@ contains a copy of the pixels.
 
 #Method static sk_sp<SkImage> MakeRasterData(const Info& info, sk_sp<SkData> pixels, size_t rowBytes)
 
+#Line # Creates Image from Image_Info and shared pixels. ##
 Creates Image from Image_Info, sharing pixels.
 
 Image is returned if Image_Info is valid. Valid Image_Info parameters include:
@@ -243,6 +245,7 @@ provided by caller when Image is created, and may be nullptr.
 #Method static sk_sp<SkImage> MakeFromRaster(const SkPixmap& pixmap,
                                          RasterReleaseProc rasterReleaseProc,
                                          ReleaseContext releaseContext)
+#Line # Creates Image from Pixmap, with release. ##
 
 Creates Image from pixmap, sharing Pixmap pixels. Pixels must remain valid and
 unchanged until rasterReleaseProc is called. rasterReleaseProc is passed
@@ -296,6 +299,7 @@ after reset: 1
 
 #Method static sk_sp<SkImage> MakeFromBitmap(const SkBitmap& bitmap)
 
+#Line # Creates Image from Bitmap, sharing or copying pixels. ##
 Creates Image from bitmap, sharing or copying bitmap pixels. If the bitmap 
 is marked immutable, and its pixel memory is shareable, it may be shared
 instead of copied.
@@ -345,6 +349,7 @@ memory does not alter the second Image.
 
 #Method static sk_sp<SkImage> MakeFromGenerator(std::unique_ptr<SkImageGenerator> imageGenerator,
                                             const SkIRect* subset = nullptr)
+#Line # Creates Image from a stream of data. ##
 
 Creates Image from data returned by imageGenerator. Generated data is owned by Image and may not
 be shared or accessed.
@@ -384,6 +389,7 @@ The generator returning Picture cannot be shared; std::move transfers ownership
 
 #Method static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr)
 
+#Line # Creates Image from encoded data. ##
 Creates Image from encoded data. 
 subset allows selecting a portion of the full image. Pass nullptr to select the entire image;
 otherwise, subset must be contained by image bounds.
@@ -422,6 +428,7 @@ for (int quality : { 100, 50, 10, 1} ) {
                                           GrSurfaceOrigin origin,
                                           SkAlphaType alphaType,
                                           sk_sp<SkColorSpace> colorSpace)
+#Line # Creates Image from GPU_Texture, managed externally. ##
 
 #Deprecated
 Deprecated.
@@ -590,6 +597,7 @@ for (auto origin : { kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin } ) {
 #Method static sk_sp<SkImage> MakeCrossContextFromEncoded(GrContext* context, sk_sp<SkData> data,
                                                       bool buildMips,
                                                       SkColorSpace* dstColorSpace)
+#Line # Creates Image from encoded data, and uploads to GPU. ##
 
 Creates Image from encoded data. Image is uploaded to GPU back-end using context. 
 
@@ -635,6 +643,7 @@ canvas->drawImage(image, 0, 0);
 #Method static sk_sp<SkImage> MakeCrossContextFromPixmap(GrContext* context, const SkPixmap& pixmap,
                                                       bool buildMips,
                                                       SkColorSpace* dstColorSpace)
+#Line # Creates Image from Pixmap, and uploads to GPU. ##
 
 Creates Image from pixmap. Image is uploaded to GPU back-end using context. 
 
@@ -684,6 +693,7 @@ if (source.peekPixels(&pixmap)) {
                                                  GrSurfaceOrigin surfaceOrigin,
                                                  SkAlphaType alphaType = kPremul_SkAlphaType,
                                                  sk_sp<SkColorSpace> colorSpace = nullptr)
+#Line # Creates Image from GPU_Texture, managed internally. ##
 
 Deprecated.
 
@@ -767,6 +777,7 @@ Recognized formats vary by GPU back-end.
                                                   const SkISize yuvSizes[3],
                                                   GrSurfaceOrigin surfaceOrigin,
                                                   sk_sp<SkColorSpace> colorSpace = nullptr)
+#Line # Creates Image from YUV_ColorSpace data in three planes. ##
 
 Creates Image from copy of yuvTextureHandles, an array of textures on GPU.
 yuvTextureHandles contain pixels for YUV planes of Image.
@@ -842,6 +853,7 @@ should this be moved to chrome only?
                                                    const SkISize nv12Sizes[2],
                                                    GrSurfaceOrigin surfaceOrigin,
                                                    sk_sp<SkColorSpace> colorSpace = nullptr)
+#Line # Creates Image from YUV_ColorSpace data in two planes. ##
 
 Creates Image from copy of nv12TextureHandles, an array of textures on GPU.
 nv12TextureHandles[0] contains pixels for YUV_Component_Y plane.
@@ -949,6 +961,7 @@ Use 16 bits per Color_ARGB component using half-precision floating point format.
                                           const SkMatrix* matrix, const SkPaint* paint,
                                           BitDepth bitDepth,
                                           sk_sp<SkColorSpace> colorSpace)
+#Line # Creates Image from Picture. ##
 
 Creates Image from picture. Returned Image width and height are set by dimensions.
 Image draws picture with matrix and paint, set to bitDepth and colorSpace.
@@ -996,6 +1009,7 @@ with default Paint. colorSpace may be nullptr.
 #Method static sk_sp<SkImage> MakeFromAHardwareBuffer(AHardwareBuffer* hardwareBuffer,
                                                  SkAlphaType alphaType = kPremul_SkAlphaType,
                                                  sk_sp<SkColorSpace> colorSpace = nullptr)
+#Line # Creates Image from Android hardware buffer. ##
 
 #Bug 7447 ##
 
@@ -1023,6 +1037,7 @@ Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
 
 #Method int width() const
 
+#Line # Returns pixel column count. ##
 Returns pixel count in each row.
 
 #Return pixel width in Image ##
@@ -1047,6 +1062,7 @@ Returns pixel count in each row.
 
 #Method int height() const
 
+#Line # Returns pixel row count. ##
 Returns pixel row count.
 
 #Return pixel height in Image ##
@@ -1072,6 +1088,7 @@ Returns pixel row count.
 
 #Method SkISize dimensions() const
 
+#Line # Returns width() and height(). ##
 Returns ISize { width(), height() }.
 
 #Return integral size of width() and height() ##
@@ -1092,6 +1109,7 @@ Returns ISize { width(), height() }.
 
 #Method SkIRect bounds() const
 
+#Line # Returns width() and height() as Rectangle. ##
 Returns IRect { 0, 0, width(), height() }.
 
 #Return integral rectangle from origin to width() and height() ##
@@ -1115,6 +1133,7 @@ Returns IRect { 0, 0, width(), height() }.
 
 #Method uint32_t uniqueID() const
 
+#Line # Identifier for Image. ##
 Returns value unique to image. Image contents cannot change after Image is
 created. Any operation to create a new Image will receive generate a new
 unique number.
@@ -1143,6 +1162,7 @@ unique number.
 
 #Method SkAlphaType alphaType() const
 
+#Line # Returns Alpha_Type. ##
 Returns Alpha_Type, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
 kPremul_SkAlphaType, kUnpremul_SkAlphaType.
 
@@ -1169,6 +1189,7 @@ or was parsed from encoded data.
 
 #Method SkColorSpace* colorSpace() const
 
+#Line # Returns Color_Space. ##
 Returns Color_Space, the range of colors, associated with Image.  The
 reference count of Color_Space is unchanged. The returned Color_Space is
 immutable.
@@ -1209,6 +1230,7 @@ is drawn, depending on the capabilities of the Surface receiving the drawing.
 
 #Method sk_sp<SkColorSpace> refColorSpace() const
 
+#Line # Returns Image_Info Color_Space. ##
 Returns a smart pointer to Color_Space, the range of colors, associated with
 Image.  The smart pointer tracks the number of objects sharing this
 SkColorSpace reference so the memory is released when the owners destruct.
@@ -1251,6 +1273,7 @@ is drawn, depending on the capabilities of the Surface receiving the drawing.
 
 #Method bool isAlphaOnly() const
 
+#Line # Returns if pixels represent a transparency mask. ##
 Returns true if Image pixels represent transparency only. If true, each pixel
 is packed in 8 bits as defined by kAlpha_8_SkColorType.
 
@@ -1273,6 +1296,7 @@ alphaOnly = true
 
 #Method bool isOpaque() const
 
+#Line # Returns if Alpha_Type is kOpaque_SkAlphaType. ##
 Returns true if pixels ignore their Alpha value and are treated as fully opaque.
 
 #Return true if Alpha_Type is kOpaque_SkAlphaType ##
@@ -1300,6 +1324,7 @@ isOpaque = true
 
 #Method sk_sp<SkShader> makeShader(SkShader::TileMode tileMode1, SkShader::TileMode tileMode2,
                                const SkMatrix* localMatrix = nullptr) const
+#Line # Creates Shader, Paint element that can tile Image. ##
 
 Creates Shader from Image. Shader dimensions are taken from Image. Shader uses
 SkShader::TileMode rules to fill drawn area outside Image. localMatrix permits
@@ -1359,6 +1384,7 @@ canvas->drawPaint(paint);
 
 #Method bool peekPixels(SkPixmap* pixmap) const
 
+#Line # Returns Pixmap if possible. ##
 Copies Image pixel address, row bytes, and Image_Info to pixmap, if address
 is available, and returns true. If pixel address is not available, return
 false and leave pixmap unchanged.
@@ -1409,6 +1435,7 @@ false and leave pixmap unchanged.
 
 #Method GrTexture* getTexture() const
 
+#Line # Deprecated. ##
 Deprecated.
  
 #Deprecated 
@@ -1424,6 +1451,7 @@ Currently used by Canvas2DLayerBridge in Chromium.
 
 #Method bool isTextureBacked() const
 
+#Line # Returns if Image was created from GPU_Texture. ##
 Returns true the contents of Image was created on or uploaded to GPU memory,
 and is available as a GPU_Texture.
 
@@ -1462,6 +1490,7 @@ drawImage(textureImage, "backEndTexture");
 
 #Method bool isValid(GrContext* context) const
 
+#Line # Returns if Image can draw to Raster_Surface or GPU_Context. ##
 Returns true if Image can be drawn on either Raster_Surface or GPU_Surface.
 If context is nullptr, tests if Image draws on Raster_Surface;
 otherwise, tests if Image draws on GPU_Surface associated with context.
@@ -1511,6 +1540,7 @@ drawImage(textureImage, "backEndTexture");
 
 #Method GrBackendObject getTextureHandle(bool flushPendingGrContextIO,
                                      GrSurfaceOrigin* origin = nullptr) const
+#Line # Returns GPU reference to Image as texture. ##
 
 Retrieves the back-end API handle of texture. If flushPendingGrContextIO is true,
 complete deferred I/O operations.
@@ -1616,6 +1646,7 @@ Disallows Skia from internally caching decoded and copied pixels.
 
 #Method bool readPixels(const SkImageInfo& dstInfo, void* dstPixels, size_t dstRowBytes,
                     int srcX, int srcY, CachingHint cachingHint = kAllow_CachingHint) const
+#Line # Copies and converts pixels. ##
 
 Copies Rect of pixels from Image to dstPixels. Copy starts at offset (srcX, srcY),
 and does not exceed Image (width(), height()). 
@@ -1762,6 +1793,7 @@ If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache
 
 #Method bool scalePixels(const SkPixmap& dst, SkFilterQuality filterQuality,
                      CachingHint cachingHint = kAllow_CachingHint) const
+#Line # Scales and converts one Image to another. ##
 
 Copies Image to dst, scaling pixels to fit dst.width() and dst.height(), and
 converting pixels to match dst.colorType and dst.alphaType. Returns true if
@@ -1821,6 +1853,7 @@ If cachingHint is kDisallow_CachingHint, pixels are not added to the local cache
 
 #Method sk_sp<SkData> encodeToData(SkEncodedImageFormat encodedImageFormat, int quality) const
 
+#Line # Returns encoded Image as SkData. ##
 Encodes Image pixels, returning result as SkData. 
 
 Returns nullptr if encoding fails, or if encodedImageFormat is not supported.
@@ -1891,6 +1924,7 @@ encoding fails.
 
 #Method sk_sp<SkData> refEncodedData() const
 
+#Line # Returns Image encoded in SkData if present. ##
 Returns encoded Image pixels as SkData, if Image was created from supported
 encoded stream format. Platform support for formats vary and may require building
 with one or more of: SK_HAS_JPEG_LIBRARY, SK_HAS_PNG_LIBRARY, SK_HAS_WEBP_LIBRARY.
@@ -1929,6 +1963,7 @@ Returns nullptr if Image contents are not encoded.
 
 #Method const char* toString(SkString* string) const
 
+#Line # Converts Image to machine readable form. ##
 Appends Image description to string, including unique ID, width, height, and
 whether the image is opaque.
 
@@ -1962,6 +1997,7 @@ whether the image is opaque.
 
 #Method sk_sp<SkImage> makeSubset(const SkIRect& subset) const
 
+#Line # Creates Image containing part of original. ##
 Returns subset of Image. subset must be fully contained by Image dimensions().
 The implementation may share pixels, or may copy them.
 
@@ -1993,6 +2029,7 @@ pixels in Image could not be read or copied.
 
 #Method sk_sp<SkImage> makeTextureImage(GrContext* context, SkColorSpace* dstColorSpace) const
 
+#Line # Creates Image matching Color_Space if possible. ##
 Returns Image backed by GPU_Texture associated with context. Returned Image is
 compatible with Surface created with dstColorSpace. Returns original
 Image if context and dstColorSpace match.
@@ -2038,6 +2075,7 @@ GrContext.
 
 #Method sk_sp<SkImage> makeNonTextureImage() const
 
+#Line # Creates Image without dependency on GPU_Texture. ##
 Returns Raster_Image or Lazy_Image. Copies Image backed by GPU_Texture into
 CPU memory if needed. Returns original Image if unencoded in Raster_Bitmap,
 or if encoded in a stream.
@@ -2078,6 +2116,7 @@ Returns nullptr if backed by GPU_Texture and copy fails.
 
 #Method sk_sp<SkImage> makeRasterImage() const
 
+#Line # Creates Image compatible with Raster_Surface if possible. ##
 Returns Raster_Image. Copies Image backed by GPU_Texture into CPU memory,
 or decodes Image from Lazy_Image. Returns original Image if unencoded in
 Raster_Bitmap.
@@ -2120,6 +2159,7 @@ Returns nullptr if copy, decode, or pixel read fails.
 #Method sk_sp<SkImage> makeWithFilter(const SkImageFilter* filter, const SkIRect& subset,
                                   const SkIRect& clipBounds, SkIRect* outSubset,
                                   SkIPoint* offset) const
+#Line # Creates filtered, clipped Image. ##
 
 Creates filtered Image. filter processes original Image, potentially changing
 color, position, and size. subset is the bounds of original Image processed
@@ -2235,6 +2275,7 @@ Used only by Chrome; to be deprecated.
                             void* buffer,
                             SkColorSpace* dstColorSpace = nullptr,
                             SkColorType dstColorType = kN32_SkColorType) const
+#Line # To be deprecated. ##
 
 Used only by Chrome; to be deprecated.
 
@@ -2303,6 +2344,7 @@ then dstColorSpace must be null.
 
 #Method static sk_sp<SkImage> MakeFromDeferredTextureImageData(GrContext* context, const void* data,
                                                            SkBudgeted budgeted)
+#Line # To be deprecated. ##
 
 Used only by Chrome; to be deprecated.
 
@@ -2336,6 +2378,7 @@ getDeferredTextureImageData.
                                               sk_sp<SkImage> image,
                                               GrBackendTexture* backendTexture,
                                               BackendTextureReleaseProc* backendTextureReleaseProc)
+#Line # Creates GPU_Texture from Image. ##
 
 Creates a GrBackendTexture from the provided SkImage. Returns true on success. The
 GrBackendTexture and BackendTextureReleaseProc are populated on success. It is the callers
@@ -2396,6 +2439,7 @@ Helper functions to convert to SkBitmap
 
 #Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode) const
 
+#Line # Returns as Raster_Bitmap. ##
 Creates raster Bitmap with same pixels as Image. If legacyBitmapMode is
 kRO_LegacyBitmapMode, returned bitmap is read-only and immutable.
 Returns true if Bitmap is stored in bitmap. Returns false and resets bitmap if
@@ -2418,6 +2462,7 @@ Bitmap write did not succeed.
 
 #Method bool isLazyGenerated() const
 
+#Line # Returns if Image is created as needed. ##
 Returns true if Image is backed by an image-generator or other service that creates
 and caches its pixels or texture on-demand.
 
@@ -2491,6 +2536,7 @@ void draw(SkCanvas* canvas) {
 
 #Method sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target,
                                   SkTransferFunctionBehavior premulBehavior) const
+#Line # Creates Image matching Color_Space if possible. ##
 
 Creates Image in target Color_Space.
 Returns nullptr if Image could not be created.