From abaffd85abb76c2c03054ba39647688299cfd204 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Thu, 15 Nov 2018 08:25:12 -0500 Subject: [PATCH] bookmaker does deprecated Bookmaker does not require documentation for public symbols described as "deprecated", "private", or "experimental". Adding one of these words (case-insensitive) to the symbol description in the include file tells bookmaker that the bmh file should not include documentation, and the generated markdown should omit it in its indices and descriptions. Symbols marked as "to be deprecated" or "may be deprecated" are still regarded as public and documented. Private notes in the includes that start with TODO: are omitted as well. This CL updated generated includes to describe its symbols accordingly. The includes will be fully regenerated in a future CL. The corresponding documentation has been deleted from the bmh files, and the web markup has been regenerated. TBR=reed@google.com Docs-Preview: https://skia.org/?cl=169830 Bug: skia: Change-Id: Ie6ec3ccdadb7be9ac15db4811823a30948c4af25 Reviewed-on: https://skia-review.googlesource.com/c/169830 Commit-Queue: Cary Clark Auto-Submit: Cary Clark Reviewed-by: Cary Clark --- docs/SkBitmap_Reference.bmh | 12 - docs/SkCanvas_Reference.bmh | 202 +-------- docs/SkImage_Reference.bmh | 51 --- docs/SkMemoryStream_Reference.bmh | 21 - docs/SkPaint_Reference.bmh | 168 -------- docs/SkPath_Reference.bmh | 4 - docs/SkPixmap_Reference.bmh | 6 - docs/SkRect_Reference.bmh | 9 +- docs/SkRegion_Reference.bmh | 12 - docs/SkStream_Reference.bmh | 4 - docs/SkSurface_Reference.bmh | 27 +- docs/SkTextBlobBuilder_Reference.bmh | 21 - docs/spelling.txt | 15 +- docs/undocumented.bmh | 1 + docs/usingBookmaker.bmh | 22 +- include/core/SkBitmap.h | 2 +- include/core/SkCanvas.h | 10 +- include/core/SkImage.h | 7 +- include/core/SkPaint.h | 7 +- include/core/SkPath.h | 4 + include/core/SkPixmap.h | 2 +- include/core/SkRect.h | 3 +- include/core/SkRegion.h | 2 +- include/core/SkSurface.h | 5 +- site/user/api/SkBitmap_Reference.md | 24 +- site/user/api/SkCanvas_Reference.md | 342 +-------------- site/user/api/SkImage_Reference.md | 81 +--- site/user/api/SkPaint_Reference.md | 322 ++------------ site/user/api/SkPath_Reference.md | 12 +- site/user/api/SkPixmap_Reference.md | 12 +- site/user/api/SkRect_Reference.md | 6 +- site/user/api/SkRegion_Reference.md | 16 +- site/user/api/SkSurface_Reference.md | 56 +-- site/user/api/SkTextBlobBuilder_Reference.md | 32 -- site/user/api/catalog.htm | 27 +- site/user/api/usingBookmaker.md | 19 +- tools/bookmaker/bmhParser.cpp | 43 +- tools/bookmaker/bookmaker.h | 7 - tools/bookmaker/definition.cpp | 41 +- tools/bookmaker/definition.h | 3 +- tools/bookmaker/hackParser.cpp | 5 +- tools/bookmaker/includeParser.cpp | 428 ++++++++++++------- tools/bookmaker/includeParser.h | 10 +- tools/bookmaker/includeWriter.cpp | 188 +++----- tools/bookmaker/mdOut.cpp | 48 +-- tools/bookmaker/parserCommon.h | 6 + tools/bookmaker/selfCheck.cpp | 4 +- tools/bookmaker/spellCheck.cpp | 6 - tools/bookmaker/textParser.h | 40 ++ 49 files changed, 529 insertions(+), 1866 deletions(-) diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh index 7a44af5035..f0b50f9f88 100644 --- a/docs/SkBitmap_Reference.bmh +++ b/docs/SkBitmap_Reference.bmh @@ -1538,12 +1538,6 @@ Draw a five by five bitmap, and draw it again with a center white pixel. ## -# ------------------------------------------------------------------------------ - -#Method bool installMaskPixels(const SkMask& mask) -#Deprecated soon -## - # ------------------------------------------------------------------------------ #Subtopic Pixels #Line # read and write pixel values ## @@ -1951,12 +1945,6 @@ erase id 6 # ------------------------------------------------------------------------------ -#Method void eraseArea(const SkIRect& area, SkColor c) const -#Deprecated -## - -# ------------------------------------------------------------------------------ - #Method SkColor getColor(int x, int y) const #In Property #In Pixels diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh index 11eb24c999..468a903877 100644 --- a/docs/SkCanvas_Reference.bmh +++ b/docs/SkCanvas_Reference.bmh @@ -189,12 +189,6 @@ void draw(SkCanvas* canvas) { # ------------------------------------------------------------------------------ -#Method explicit SkCanvas(sk_sp device) -#Deprecated soon -## - -# ------------------------------------------------------------------------------ - #Method explicit SkCanvas(const SkBitmap& bitmap) #Line # uses existing Bitmap ## @@ -243,30 +237,6 @@ The actual output depends on the installed fonts. ## -#EnumClass ColorBehavior -#Line # exists for Android framework only ## -#Private -Android framework only. -## - -#Code -#Populate -## -#Const kLegacy 0 -#Line # placeholder ## - Is a placeholder to allow specialized constructor; has no meaning. -## -## - -#Method SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior) - -#Line # exists for Android framework only ## -#Populate - -#NoExample -## -## - # ------------------------------------------------------------------------------ #Method SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props) @@ -446,7 +416,7 @@ void draw(SkCanvas* canvas) { #NoExample ## -#SeeAlso peekPixels SkSurface::flush GrContext::flush SkSurface::prepareForExternalIO GrContext::abandonContext +#SeeAlso peekPixels SkSurface::flush GrContext::flush GrContext::abandonContext ## @@ -1374,14 +1344,6 @@ kPreserveLCDText_SaveLayerFlag, kInitWithPrevious_SaveLayerFlag, or both flags. Initializes Layer with the contents of the previous Layer. ## -#Const kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag 8 -#Experimental do not use -## - -#Const kDontClipToLayer_Legacy_SaveLayerFlag 0x80000000 -#Deprecated soon -## - #Example #Height 160 #Description @@ -1550,37 +1512,6 @@ void draw(SkCanvas* canvas) { ## -#Method SaveLayerRec(const SkRect* bounds, const SkPaint* paint, const SkImageFilter* backdrop, - const SkImage* clipMask, const SkMatrix* clipMatrix, - SaveLayerFlags saveLayerFlags) - -#Experimental not ready - -Sets fBounds, fPaint, fBackdrop, fClipMask, fClipMatrix, and fSaveLayerFlags. -clipMatrix uses Color_Alpha channel of image, transformed by clipMatrix, to clip -Layer when drawn to Canvas. - -Implementation is not complete; has no effect if Device is GPU-backed. - -#Param bounds Layer dimensions; may be nullptr ## -#Param paint graphics state applied to Layer when overlaying prior - Layer; may be nullptr -## -#Param backdrop prior Layer copied with Image_Filter; - may be nullptr -## -#Param clipMask clip applied to Layer; may be nullptr ## -#Param clipMatrix matrix applied to clipMask; may be nullptr to use - identity matrix -## -#Param saveLayerFlags SaveLayerRec options to modify Layer ## - -#Return SaveLayerRec fully specified ## - -#SeeAlso save restore saveLayer saveLayerPreserveLCDTextRequests saveLayerAlpha - -## - #Struct ## #Subtopic ## @@ -2025,26 +1956,6 @@ void draw(SkCanvas* canvas) { ## -#Method void androidFramework_setDeviceClipRestriction(const SkIRect& rect) - -#In Clip -#Line # exists for use by Android framework ## -Sets the maximum clip rectangle, which can be set by clipRect, clipRRect and -clipPath and intersect the current clip with the specified rect. -The maximum clip affects only future clipping operations; it is not retroactive. -The clip restriction is not recorded in pictures. - -Pass an empty rect to disable maximum clip. - -#Private -This private API is for use by Android framework only. -## - -#Param rect maximum allowed clip in device coordinates -#Param ## - -## - #Method void clipRRect(const SkRRect& rrect, SkClipOp op, bool doAntiAlias) #In Clip @@ -2214,17 +2125,6 @@ void draw(SkCanvas* canvas) { # ------------------------------------------------------------------------------ -#Method void setAllowSimplifyClip(bool allow) - -#In Clip -#Experimental testing - -Set to simplify clip stack using PathOps. - -## - -# ------------------------------------------------------------------------------ - #Method void clipRegion(const SkRegion& deviceRgn, SkClipOp op = SkClipOp::kIntersect) #In Clip @@ -2520,7 +2420,7 @@ void draw(SkCanvas* canvas) { #NoExample ## -#SeeAlso flush() SkSurface::prepareForExternalIO GrContext::abandonContext +#SeeAlso flush() GrContext::abandonContext ## @@ -4012,104 +3912,6 @@ void draw(SkCanvas* canvas) { #Subtopic Lattice ## -# ------------------------------------------------------------------------------ - -#Enum QuadAAFlags -#Line # do not use this ## -#Code -#Populate -## - -#Private -Do not use. -## - -#Const kLeft_QuadAAFlag 1 -#Line # antialias the left edge ## -## - -#Const kTop_QuadAAFlag 2 -#Line # antialias the top edge ## -## - -#Const kRight_QuadAAFlag 4 -#Line # antialias the right edge ## -## - -#Const kBottom_QuadAAFlag 8 -#Line # antialias the bottom edge ## -## - -#Const kNone_QuadAAFlags 0 -#Line # antialias none of the edges ## -## - -#Const kAll_QuadAAFlags 15 -#Line # antialias all of the edges ## -## - -#NoExample -## -## - -# ------------------------------------------------------------------------------ - -#Struct ImageSetEntry -#Line # do not use this ## - -#Code -#Populate -## - -#Private -Do not use. -## - -#Member SkImage* fImage -#Line # image to draw ## -## - -#Member SkRect fSrcRect -#Line # image src rectangle ## -## - -#Member SkRect fDstRect -#Line # local space rectangle ## -## - -#Member unsigned fAAFlags -#Line # antialiasing flags ## -## - -#NoExample -## - -## - -# ------------------------------------------------------------------------------ - -#Method void experimental_DrawImageSetV0(const ImageSetEntry imageSet[], int cnt, float alpha, - SkFilterQuality quality, SkBlendMode mode); -#Private -Do not use. -## -#In Draw_Image -#In Draw -#Line # draws a set a of images; do not call this ## - -Draws a set of images. Do not use this method. - -#Param imageSet images ## -#Param cnt number of images ## -#Param alpha alpha ## -#Param quality filter quality ## -#Param mode blend mode ## - -#NoExample -## - -## - #Subtopic Draw_Image ## # ------------------------------------------------------------------------------ diff --git a/docs/SkImage_Reference.bmh b/docs/SkImage_Reference.bmh index 9a6874065e..97538cd5a7 100644 --- a/docs/SkImage_Reference.bmh +++ b/docs/SkImage_Reference.bmh @@ -999,12 +999,6 @@ canvas->drawPaint(paint); # ------------------------------------------------------------------------------ -#Method GrTexture* getTexture() const -#Deprecated -#Method ## - -# ------------------------------------------------------------------------------ - #Method bool isTextureBacked() const #In Property #Line # returns if Image was created from GPU_Texture ## @@ -1624,51 +1618,6 @@ void draw(SkCanvas* canvas) { # ------------------------------------------------------------------------------ -#Enum LegacyBitmapMode -#Deprecated soon -#Code -#Populate -## - -#Const kRO_LegacyBitmapMode 0 -#Line # returned bitmap is read-only and immutable ## -## - -#Enum ## - -# ------------------------------------------------------------------------------ - -#Method bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const -#In Constructors -#Line # returns as Raster_Bitmap ## -#Populate - -#Example -#Image 4 -#Platform gpu - SkBitmap bitImage; - if (image->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) { - canvas->drawBitmap(bitImage, 0, 0); - } - GrContext* grContext = canvas->getGrContext(); - if (!grContext) { - return; - } - sk_sp textureImage(SkImage::MakeFromTexture(grContext, backEndTexture, - kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType, - kOpaque_SkAlphaType, nullptr)); - canvas->drawImage(textureImage, 45, 45); - if (textureImage->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) { - canvas->drawBitmap(bitImage, 90, 90); - } -## - -#SeeAlso MakeRasterData makeRasterImage makeNonTextureImage - -#Method ## - -# ------------------------------------------------------------------------------ - #Method bool isLazyGenerated() const #In Property #Line # returns if Image is created as needed ## diff --git a/docs/SkMemoryStream_Reference.bmh b/docs/SkMemoryStream_Reference.bmh index 3bcbe67522..b7e86b0c6d 100644 --- a/docs/SkMemoryStream_Reference.bmh +++ b/docs/SkMemoryStream_Reference.bmh @@ -173,27 +173,6 @@ if copyData is true, the stream makes a private copy of the data # ------------------------------------------------------------------------------ -#Method void setMemoryOwned(const void* data, size_t length) -#In incomplete -#Line # incomplete ## - -#Private -Internal use only. -## - -#Param data incomplete ## -#Param length incomplete ## - -#Example -// incomplete -## - -#SeeAlso incomplete - -#Method ## - -# ------------------------------------------------------------------------------ - #Method sk_sp asData() const #In incomplete #Line # incomplete ## diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh index 373be0e509..98067ae6d2 100644 --- a/docs/SkPaint_Reference.bmh +++ b/docs/SkPaint_Reference.bmh @@ -296,28 +296,6 @@ $$$# # restore original markup character #Line # glyph outline adjustment ## ## -#Enum Hinting -#Line # level of glyph outline adjustment ## - -#Code -#Populate -## - -#Const kNo_Hinting 0 -#Deprecated -## -#Const kSlight_Hinting 1 -#Deprecated -## -#Const kNormal_Hinting 2 -#Deprecated -## -#Const kFull_Hinting 3 -#Deprecated -## - -## - #Method void setHinting(SkFontHinting hintingLevel) #In Hinting #Line # sets Hinting, glyph outline adjustment level ## @@ -334,26 +312,6 @@ $$$# # restore original markup character ## ## -#Method Hinting getHinting() const -#In Hinting -#Line # returns Hinting, glyph outline adjustment level ## -#Populate -#NoExample -## -## - -#Method void setHinting(Hinting h) -#In Hinting -#Line # returns Hinting, glyph outline adjustment level ## -#Populate -#NoExample -## -## - -# Disable for now -#ToDo no spelling errors -###$ block comment - #Method SkFontHinting getHinting() const #In Hinting #Line # returns Hinting, glyph outline adjustment level ## @@ -370,9 +328,6 @@ $$$# # restore original markup character ## ## -$$$# end of block comment -#ToDo ## - # ------------------------------------------------------------------------------ #Subtopic Flags #Line # attributes represented by single bits ## @@ -424,23 +379,6 @@ Flags default to all flags clear, disabling the associated feature. #Enum ## -#Enum ReserveFlags -#Deprecated soon - -Only valid for Android framework. - -#Code -#Populate -## - -#Const kUnderlineText_ReserveFlag 0x0008 -#Deprecated soon -## -#Const kStrikeThruText_ReserveFlag 0x0010 -#Deprecated soon -## -## - #Method uint32_t getFlags() const #In Flags #Line # returns Flags stored in a bit field ## @@ -2893,11 +2831,6 @@ Set Draw_Looper to nullptr to prevent Draw_Looper from modifying the draw. ## -#Method SkDrawLooper* getLooper() const -#Bug 6259 -#Deprecated -## - #Method void setDrawLooper(sk_sp drawLooper) #In Draw_Looper_Methods #Line # sets Draw_Looper, multiple layers ## @@ -2918,11 +2851,6 @@ Set Draw_Looper to nullptr to prevent Draw_Looper from modifying the draw. ## -#Method void setLooper(sk_sp drawLooper) -#Bug 6259 -#Deprecated -## - #Subtopic Draw_Looper_Methods ## #Subtopic Text_Size @@ -3778,102 +3706,6 @@ void draw(SkCanvas* canvas) { ## -# ------------------------------------------------------------------------------ -#Subtopic Fast_Bounds -#Line # approximate area required by Paint ## - #Private - To be made private. - ## - -Fast_Bounds functions conservatively outset a drawing bounds by additional area -Paint may draw to. - -#Method bool canComputeFastBounds() const - -#In Fast_Bounds -#Line # returns true if settings allow for fast bounds computation ## - #Private - (to be made private) - ## - - Returns true if Paint does not include elements requiring extensive computation - to compute Device bounds of drawn geometry. For instance, Paint with Path_Effect - always returns false. - - #Return true if Paint allows for fast computation of bounds ## -## - -#Method const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const - -#In Fast_Bounds -#Line # returns fill bounds for quick reject tests ## - #Private - (to be made private) - ## - - Only call if canComputeFastBounds returned true. This takes a - raw rectangle, the raw bounds of a shape; and adjusts it for stylistic - effects in the paint, such as stroking. If needed, it uses the storage - parameter. It returns the adjusted bounds that can then be used - for SkCanvas::quickReject tests. - - The returned Rect will either be orig or storage, thus the caller - should not rely on storage being set to the result, but should always - use the returned value. It is legal for orig and storage to be the same - Rect. - - #Private - For example: - if (!path.isInverseFillType() && paint.canComputeFastBounds()) { - SkRect storage; - if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) { - return; // do not draw the path - } - } - // draw the path - ## - - #Param orig geometry modified by Paint when drawn ## - #Param storage computed bounds of geometry; may not be nullptr ## - - #Return fast computed bounds ## -## - -#Method const SkRect& computeFastStrokeBounds(const SkRect& orig, - SkRect* storage) const -#In Fast_Bounds -#Line # returns stroke bounds for quick reject tests ## - #Private - (to be made private) - ## - - #Param orig geometry modified by Paint when drawn ## - #Param storage computed bounds of geometry ## - - #Return fast computed bounds ## -## - -#Method const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, - Style style) const -#In Fast_Bounds -#Line # returns bounds for quick reject tests ## - #Private - (to be made private) - ## - - Computes the bounds, overriding the Paint Style. This can be used to - account for additional width required by stroking orig, without - altering Style set to fill. - - #Param orig geometry modified by Paint when drawn ## - #Param storage computed bounds of geometry ## - #Param style overrides Style ## - - #Return fast computed bounds ## -## - -#Subtopic Fast_Bounds ## - # ------------------------------------------------------------------------------ #Subtopic Utility #Line # rarely called management functions ## diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh index 335283225d..11d0b5308a 100644 --- a/docs/SkPath_Reference.bmh +++ b/docs/SkPath_Reference.bmh @@ -4350,10 +4350,6 @@ empty genID = 1 ## -#Method bool pathRefIsValid() const -#Deprecated soon -## - # ------------------------------------------------------------------------------ #Class Iter diff --git a/docs/SkPixmap_Reference.bmh b/docs/SkPixmap_Reference.bmh index 1b38cc37f6..b012f34578 100644 --- a/docs/SkPixmap_Reference.bmh +++ b/docs/SkPixmap_Reference.bmh @@ -177,12 +177,6 @@ is not unique # ------------------------------------------------------------------------------ -#Method bool reset(const SkMask& mask) -#Deprecated soon -## - -# ------------------------------------------------------------------------------ - #Method bool extractSubset(SkPixmap* subset, const SkIRect& area) const #In Initialization diff --git a/docs/SkRect_Reference.bmh b/docs/SkRect_Reference.bmh index a776adcab3..fa34825db0 100644 --- a/docs/SkRect_Reference.bmh +++ b/docs/SkRect_Reference.bmh @@ -639,14 +639,7 @@ test with NaN is not equal to itself #In As_Points #Line # returns four corners as Point ## -Returns four points in quad that enclose Rect ordered as: top-left, top-right, -bottom-right, bottom-left. - -#Private -Consider adding param to control whether quad is clockwise or counterclockwise. -## - -#Param quad storage for corners of Rect ## +#Populate #Example SkRect rect = {1, 2, 3, 4}; diff --git a/docs/SkRegion_Reference.bmh b/docs/SkRegion_Reference.bmh index 7e72f6ae2f..50ada6793c 100644 --- a/docs/SkRegion_Reference.bmh +++ b/docs/SkRegion_Reference.bmh @@ -1530,18 +1530,6 @@ May be used to verify that Op is a legal value. # ------------------------------------------------------------------------------ -#Method char* toString() -#In Utility -#Line # exists for Android framework only ## -#Private -Android framework only. -## -#Return string representation of Region ## - -#Method ## - -# ------------------------------------------------------------------------------ - #Method size_t writeToMemory(void* buffer) const #In Utility #Line # writes to buffer ## diff --git a/docs/SkStream_Reference.bmh b/docs/SkStream_Reference.bmh index a9276396cf..c94b6f9d49 100644 --- a/docs/SkStream_Reference.bmh +++ b/docs/SkStream_Reference.bmh @@ -505,10 +505,6 @@ Returns the total length of the stream. If this cannot be done, returns 0. Returns the starting address for the data. If this cannot be done, returns nullptr. -#Private -TODO: replace with virtual const SkData* getData() -## - #Return incomplete ## #Example diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh index ee2e93fa91..32999c5226 100644 --- a/docs/SkSurface_Reference.bmh +++ b/docs/SkSurface_Reference.bmh @@ -606,16 +606,7 @@ If a snapshot has been generated, this copies the Surface contents. #Method void notifyContentWillChange(ContentChangeMode mode) #In Miscellaneous #Line # notifies that contents will be changed outside of Skia ## -Notifies that Surface contents will be changed by code outside of Skia. -Subsequent calls to generationID return a different value. - -mode is normally passed as kRetain_ContentChangeMode. - -#Private -Can we deprecate this? -## - -#Param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode ## +#Populate #Example auto surface = SkSurface::MakeRasterN32Premul(1, 1); @@ -665,16 +656,6 @@ Caller may write to the back-end object. Caller must overwrite the entire back-end object. ## -#Const kFlushRead_TextureHandleAccess 0 -#Deprecated -## -#Const kFlushWrite_TextureHandleAccess 1 -#Deprecated -## -#Const kDiscardWrite_TextureHandleAccess 2 -#Deprecated -## - #NoExample // todo: need to update example to use GrBackendTexture instead of GrBackendObject #Platform gpu @@ -1143,12 +1124,6 @@ surf.props(): kRGB_H_SkPixelGeometry #Method ## -# ------------------------------------------------------------------------------ - -#Method void prepareForExternalIO() -#Deprecated soon -#Method ## - # ------------------------------------------------------------------------------ #Subtopic Utility #Line # rarely called management functions ## diff --git a/docs/SkTextBlobBuilder_Reference.bmh b/docs/SkTextBlobBuilder_Reference.bmh index 9ca937daf5..1e9fd92e73 100644 --- a/docs/SkTextBlobBuilder_Reference.bmh +++ b/docs/SkTextBlobBuilder_Reference.bmh @@ -196,27 +196,6 @@ const SkRect* bounds = nullptr) #Method ## -# ------------------------------------------------------------------------------ - -#Method const RunBuffer& allocRun(const SkPaint& font, int count, SkScalar x, SkScalar y, - const SkRect* bounds = nullptr) -#Deprecated -#Method ## - -# ------------------------------------------------------------------------------ - -#Method const RunBuffer& allocRunPosH(const SkPaint& font, int count, SkScalar y, - const SkRect* bounds = nullptr) -#Deprecated -#Method ## - -# ------------------------------------------------------------------------------ - -#Method const RunBuffer& allocRunPos(const SkPaint& font, int count, - const SkRect* bounds = nullptr) -#Deprecated -#Method ## - #Class SkTextBlobBuilder ## #Topic Text_Blob_Builder ## diff --git a/docs/spelling.txt b/docs/spelling.txt index 5d9075e373..7caf9ef39e 100644 --- a/docs/spelling.txt +++ b/docs/spelling.txt @@ -35,7 +35,7 @@ compatibility compatible compile compiled compiler complete completely completes complexity complicated component components composed composite compositing composition compressed computation computations compute computed computes computing concatenated concatenates concatenation concave concert condensed condition configuration conical -connect connected connecting connects consecutive conservative conservatively +connect connected connecting connects consecutive conservative conservatively consider consideration considered considers consistent consists const constant constants constrained constraint construct constructed constructing construction constructions constructor constructs @@ -51,8 +51,8 @@ cumulatively current curvature curving custom cyan dark darken darkening darker dashed dashes dashing debug decimal decimated declaring decode decoded decoders decodes decoding -decomposed decomposes decomposing decrease decreased decreases decreasing decrements default defaults -defer deferred +decomposed decomposes decomposing decrease decreased decreases decreasing decrements default +defaults defer deferred defers define defined defines defining definition deform deformations degenerate degree degrees delete deleted deletes deleting dependent depending depends deprecated depth descent describe described describes describing description descriptions descriptor @@ -76,7 +76,8 @@ exceptions excess exchanged exchanges exchanging exclude excluded exclusive exec execution exhausted existing expanded expansion expected expecting explicit explicitly exponent exposed expression extend extended extends extension extensive extent extra extract eye -face faces factor factored factors fail failing fails failure fake fall false far fast faster fastest +face faces factor factored factors fail failing fails failure fake fall false far fast faster +fastest favor feature features fewer fidelity field fields figure file fill filled filling fills filter filtered filtering filters final finalized finally find fine finite first fit fits fitted five fix @@ -91,7 +92,8 @@ geometries geometry get gets gigabyte gigabytes given gives global globally go g good gradient gradients graphics gray gray-level greater greatest green grid grows guarantee guaranteed guard -had hairline hairlines half half-precision halved hand handle handling hands happens hard hardware has hash +had hairline hairlines half half-precision halved hand handle handling hands happens hard hardware +has hash hashes have heap height help helper helpers helpful here hexadecimal hidden hierarchical high higher highest hint hinted hinting hints hit hitting hold holding holds hole holes horizontal horizontally host hosts hour how however hue hyperbola hyperbolic @@ -223,7 +225,8 @@ there therefore these they thick thickness thin thinner thinnest third third-ord those though thought thread threads three three-dimensional through thus tight tile tiles tiling time times to together toggled too top top-left top-right total totaling touches towards tracked tracks -trades trading traditional transferred transferring transfers transform transformation transformations +trades trading traditional transferred transferring transfers transform transformation +transformations transformed transforming transforms transition transitions translate translated translates translating translation translucent transparency transparent travel traveled treat treated treating treats triangle trigger triggered triggers trivial true try turned turns twice two diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh index 2c5d965bb0..68fdc4b86a 100644 --- a/docs/undocumented.bmh +++ b/docs/undocumented.bmh @@ -16,6 +16,7 @@ malloc() calloc() assert() std::move() C C++ SIZE_MAX C_FILE FILE CSS HTML + affine destructor multitexturing representable subclasses descender descenders grayscale kerning unhinted diff --git a/docs/usingBookmaker.bmh b/docs/usingBookmaker.bmh index 02256a216a..a3413b20d4 100644 --- a/docs/usingBookmaker.bmh +++ b/docs/usingBookmaker.bmh @@ -107,25 +107,9 @@ To fix this, edit the docs file corresponding to the changed include file. For instance, if the change was made to SkIRect, edit docs/SkIRect_Reference.bmh. Checking in the edited docs/SkIRect_Reference.bmh will fix the bot. -If the interface is deprecated, but still present in the interface, mark-up the -documentation to be deprecated as well. - -#Code -###$ -#Method void someMethodThatIsNowDeprecated() -#Deprecated -## -$$ - -Use - -$Code -#Deprecated soon -$$ - -if the change is soon to be deprecated. - -$$$# +If the interface is deprecated, private, or experimental, documentation is not +required. Put the word "Deprecated", "Private", or "Experimental"; upper or lower +case, in a comment just before the symbol to be ignored. If #A Housekeeper-Nightly-Bookmaker # https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-Nightly-Bookmaker ## diff --git a/include/core/SkBitmap.h b/include/core/SkBitmap.h index 1fd19f02ac..0b7339db27 100644 --- a/include/core/SkBitmap.h +++ b/include/core/SkBitmap.h @@ -654,7 +654,7 @@ public: */ bool installPixels(const SkPixmap& pixmap); - /** To be deprecated soon. + /** Deprecated. */ bool installMaskPixels(const SkMask& mask); diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h index 6b42b42fea..7161f99e11 100644 --- a/include/core/SkCanvas.h +++ b/include/core/SkCanvas.h @@ -162,7 +162,7 @@ public: */ SkCanvas(int width, int height, const SkSurfaceProps* props = nullptr); - /** To be deprecated soon. + /** Deprecated. */ explicit SkCanvas(sk_sp device); @@ -181,11 +181,13 @@ public: explicit SkCanvas(const SkBitmap& bitmap); #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK + /** Private. + */ enum class ColorBehavior { kLegacy, //!< placeholder }; - /** For use by Android framework only. + /** Private. For use by Android framework only. @param bitmap specifies a bitmap for the canvas to draw into @param behavior specializes this constructor; value is unused @@ -610,7 +612,7 @@ public: #ifdef SK_SUPPORT_LEGACY_CLIPTOLAYERFLAG kDontClipToLayer_Legacy_SaveLayerFlag = - kDontClipToLayer_PrivateSaveLayerFlag, //!< to be deprecated soon + kDontClipToLayer_PrivateSaveLayerFlag, //!< deprecated #endif }; @@ -1809,7 +1811,7 @@ public: const SkPaint* paint = nullptr); /** - * Controls anti-aliasing of each edge of images in an image-set. + * Experimental. Controls anti-aliasing of each edge of images in an image-set. */ enum QuadAAFlags : unsigned { kLeft_QuadAAFlag = 0b0001, diff --git a/include/core/SkImage.h b/include/core/SkImage.h index b76130cab4..79067af119 100644 --- a/include/core/SkImage.h +++ b/include/core/SkImage.h @@ -964,17 +964,20 @@ public: GrBackendTexture* backendTexture, BackendTextureReleaseProc* backendTextureReleaseProc); + /** Deprecated. + */ enum LegacyBitmapMode { kRO_LegacyBitmapMode, //!< returned bitmap is read-only and immutable }; - /** Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is + /** Deprecated. + Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is kRO_LegacyBitmapMode, returned bitmap is read-only and immutable. Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if SkBitmap write did not succeed. @param bitmap storage for legacy SkBitmap - @param legacyBitmapMode to be deprecated + @param legacyBitmapMode bitmap is read-only and immutable @return true if SkBitmap was created */ bool asLegacyBitmap(SkBitmap* bitmap, diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h index 3ae2a66bfd..b43ecc657d 100644 --- a/include/core/SkPaint.h +++ b/include/core/SkPaint.h @@ -186,6 +186,7 @@ public: void reset(); /** \enum SkPaint::Hinting + Deprecated. Hinting adjusts the glyph outlines so that the shape provides a uniform look at a given point size on font engines that support it. Hinting may have a muted effect or no effect at all depending on the platform. @@ -209,13 +210,13 @@ public: void setHinting(SkFontHinting hintingLevel); #ifdef SK_SUPPORT_LEGACY_NESTED_HINTINGENUM - /** Returns level of glyph outline adjustment. + /** Deprecated. Returns level of glyph outline adjustment. @return one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting */ Hinting getHinting() const { return (Hinting)fBitfields.fHinting; } - /** Sets level of glyph outline adjustment. + /** Deprecated. Sets level of glyph outline adjustment. Does not check for valid values of h. @param h one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting @@ -253,6 +254,8 @@ public: }; #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK + /** Private. + */ enum ReserveFlags { kUnderlineText_ReserveFlag = 0x08, //!< to be deprecated soon kStrikeThruText_ReserveFlag = 0x10, //!< to be deprecated soon diff --git a/include/core/SkPath.h b/include/core/SkPath.h index 9b1e324a48..9192419110 100644 --- a/include/core/SkPath.h +++ b/include/core/SkPath.h @@ -1678,7 +1678,11 @@ public: */ bool isValid() const { return this->isValidImpl() && fPathRef->isValid(); } #else + /** Deprecated. + */ bool isValid() const { return this->isValidImpl(); } + /** Deprecated. + */ bool pathRefIsValid() const { return fPathRef->isValid(); } #endif diff --git a/include/core/SkPixmap.h b/include/core/SkPixmap.h index 94c7e988e5..5c15876d77 100644 --- a/include/core/SkPixmap.h +++ b/include/core/SkPixmap.h @@ -106,7 +106,7 @@ public: */ void setColorSpace(sk_sp colorSpace); - /** To be deprecated soon. + /** Deprecated. */ bool SK_WARN_UNUSED_RESULT reset(const SkMask& mask); diff --git a/include/core/SkRect.h b/include/core/SkRect.h index cf309cda1b..1748955e89 100644 --- a/include/core/SkRect.h +++ b/include/core/SkRect.h @@ -934,7 +934,8 @@ struct SK_API SkRect { /** Returns four points in quad that enclose SkRect ordered as: top-left, top-right, bottom-right, bottom-left. - Consider adding param to control whether quad is clockwise or counterclockwise. + + TODO: Consider adding parameter to control whether quad is clockwise or counterclockwise. @param quad storage for corners of SkRect */ diff --git a/include/core/SkRegion.h b/include/core/SkRegion.h index b353484ec4..c5bd825cec 100644 --- a/include/core/SkRegion.h +++ b/include/core/SkRegion.h @@ -453,7 +453,7 @@ public: bool op(const SkRegion& rgna, const SkRegion& rgnb, Op op); #ifdef SK_BUILD_FOR_ANDROID - /** Android framework only. + /** Private. Android framework only. @return string representation of SkRegion */ diff --git a/include/core/SkSurface.h b/include/core/SkSurface.h index 1936f4417f..0c7d36a264 100644 --- a/include/core/SkSurface.h +++ b/include/core/SkSurface.h @@ -412,8 +412,7 @@ public: /** Notifies that SkSurface contents will be changed by code outside of Skia. Subsequent calls to generationID() return a different value. - mode is normally passed as kRetain_ContentChangeMode. - Can we deprecate this? + TODO: Can kRetain_ContentChangeMode be deprecated? @param mode one of: kDiscard_ContentChangeMode, kRetain_ContentChangeMode */ @@ -647,7 +646,7 @@ public: */ const SkSurfaceProps& props() const { return fProps; } - /** To be deprecated soon. + /** Deprecated. */ void prepareForExternalIO(); diff --git a/site/user/api/SkBitmap_Reference.md b/site/user/api/SkBitmap_Reference.md index fc05ed2ce4..c41a0a7443 100644 --- a/site/user/api/SkBitmap_Reference.md +++ b/site/user/api/SkBitmap_Reference.md @@ -64,7 +64,7 @@ public: void (*releaseProc)(void* addr, void* context), void* context); bool installPixels(const SkImageInfo& info, void* pixels, size_t rowBytes); bool installPixels(const SkPixmap& pixmap); - bool installMaskPixels(const SkMask& mask); + bool installMaskPixels(const SkMask& mask); void setPixels(void* pixels); bool tryAllocPixels(); void allocPixels(); @@ -79,7 +79,7 @@ public: void eraseColor(SkColor c) const; void eraseARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) const; void erase(SkColor c, const SkIRect& area) const; - void eraseArea(const SkIRect& area, SkColor c) const; + void eraseArea(const SkIRect& area, SkColor c) const; SkColor getColor(int x, int y) const; float getAlphaf(int x, int y) const; void* getAddr(int x, int y) const; @@ -2101,16 +2101,6 @@ true if SkImageInfo was set to < allocPixels - - ---- - -
-bool installMaskPixels(const SkMask& mask)
-
- -To be deprecated soon. - @@ -2549,16 +2539,6 @@ then RGB is ignored. eraseColor eraseARGB SkCanvas::drawRect - - ---- - -
-void eraseArea(const SkIRect& area, SkColor c) const
-
- -Deprecated. - --- diff --git a/site/user/api/SkCanvas_Reference.md b/site/user/api/SkCanvas_Reference.md index 5885058c7e..6bf9d4d1cc 100644 --- a/site/user/api/SkCanvas_Reference.md +++ b/site/user/api/SkCanvas_Reference.md @@ -19,11 +19,11 @@ public: explicit SkCanvas(sk_sp<SkBaseDevice> device); explicit SkCanvas(const SkBitmap& bitmap); - enum class ColorBehavior { + enum class ColorBehavior { kLegacy, }; - SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior); + SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior); SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props); virtual ~SkCanvas(); SkMetaData& getMetaData(); @@ -51,9 +51,9 @@ public: enum SaveLayerFlagsSet { kPreserveLCDText_SaveLayerFlag = 1 << 1, kInitWithPrevious_SaveLayerFlag = 1 << 2, - kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag = + kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag = 1 << 3, - kDontClipToLayer_Legacy_SaveLayerFlag = + kDontClipToLayer_Legacy_SaveLayerFlag = kDontClipToLayer_PrivateSaveLayerFlag, }; @@ -90,14 +90,14 @@ public: void clipRect(const SkRect& rect, SkClipOp op, bool doAntiAlias); void clipRect(const SkRect& rect, SkClipOp op); void clipRect(const SkRect& rect, bool doAntiAlias = false); - void androidFramework_setDeviceClipRestriction(const SkIRect& rect); + void androidFramework_setDeviceClipRestriction(const SkIRect& rect); void clipRRect(const SkRRect& rrect, SkClipOp op, bool doAntiAlias); void clipRRect(const SkRRect& rrect, SkClipOp op); void clipRRect(const SkRRect& rrect, bool doAntiAlias = false); void clipPath(const SkPath& path, SkClipOp op, bool doAntiAlias); void clipPath(const SkPath& path, SkClipOp op); void clipPath(const SkPath& path, bool doAntiAlias = false); - void setAllowSimplifyClip(bool allow); + void setAllowSimplifyClip(bool allow); void clipRegion(const SkRegion& deviceRgn, SkClipOp op = SkClipOp::kIntersect); bool quickReject(const SkRect& rect) const; bool quickReject(const SkPath& path) const; @@ -196,23 +196,23 @@ public: void drawImageLattice(const SkImage* image, const Lattice& lattice, const SkRect& dst, const SkPaint* paint = nullptr); - enum QuadAAFlags : unsigned { - kLeft_QuadAAFlag = 0b0001, - kTop_QuadAAFlag = 0b0010, - kRight_QuadAAFlag = 0b0100, - kBottom_QuadAAFlag = 0b1000, - kNone_QuadAAFlags = 0b0000, - kAll_QuadAAFlags = 0b1111, + enum QuadAAFlags : unsigned { + kLeft_QuadAAFlag = 0b0001, + kTop_QuadAAFlag = 0b0010, + kRight_QuadAAFlag = 0b0100, + kBottom_QuadAAFlag = 0b1000, + kNone_QuadAAFlags = 0b0000, + kAll_QuadAAFlags = 0b1111, }; - struct ImageSetEntry { + struct ImageSetEntry { sk_spSkImage> fImage; SkRect fSrcRect; SkRect fDstRect; unsigned fAAFlags; }; - void experimental_DrawImageSetV0(const ImageSetEntry imageSet[], int cnt, float alpha, + void experimental_DrawImageSetV0(const ImageSetEntry imageSet[], int cnt, float alpha, SkFilterQuality quality, SkBlendMode mode); void drawText(const void* text, size_t byteLength, SkScalar x, SkScalar y, const SkPaint& paint); @@ -519,16 +519,6 @@ canvas is empty MakeRasterDirect SkSurfaceProps SkPixelGeometry SkCreateColorSpaceXformCanvas - - ---- - -
-explicit SkCanvas(sk_sp<SkBaseDevice> device)
-
- -To be deprecated soon. - --- @@ -585,57 +575,6 @@ storage of raster surface MakeRasterDirect SkRasterHandleAllocator::MakeCanvas SkSurface::getCanvas SkCreateColorSpaceXformCanvas - - ---- - -Private: Android framework only. - -
-    enum class ColorBehavior {
-        kLegacy,
-    };
-
- -### Constants - - - - - - - - - - -
ConstValueDescription
SkCanvas::ColorBehavior::kLegacy0 -Is a placeholder to allow specialized constructor; has no meaning. -
- - - ---- - -
-SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior)
-
- -For use by Android framework only. - -### Parameters - - - - - - - -
bitmapspecifies a bitmap for the canvas to draw into
behaviorspecializes this constructor; value is unused
- -### Return Value - -SkCanvas that can be used to draw into bitmap - --- @@ -844,7 +783,7 @@ operations are never deferred. ### See Also -peekPixels SkSurface::flush GrContext::flush SkSurface::prepareForExternalIO GrContext::abandonContext +peekPixels SkSurface::flush GrContext::flush GrContext::abandonContext @@ -1867,9 +1806,9 @@ depth of saved stack enum SaveLayerFlagsSet { kPreserveLCDText_SaveLayerFlag = 1 << 1, kInitWithPrevious_SaveLayerFlag = 1 << 2, - kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag = + kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag = 1 << 3, - kDontClipToLayer_Legacy_SaveLayerFlag = + kDontClipToLayer_Legacy_SaveLayerFlag = kDontClipToLayer_PrivateSaveLayerFlag, }; @@ -1901,22 +1840,6 @@ Creates Layer for 4 Initializes Layer with the contents of the previous Layer. - - - - SkCanvas::kMaskAgainstCoverage_EXPERIMENTAL_DONT_USE_SaveLayerFlag - 8 - -Experimental. Do not use. - - - - - SkCanvas::kDontClipToLayer_Legacy_SaveLayerFlag - 0x80000000 - -To be deprecated soon. - @@ -2150,59 +2073,6 @@ rec1 == rec2 save restore saveLayer saveLayerPreserveLCDTextRequests saveLayerAlpha - - ---- - -
-SaveLayerRec(const SkRect* bounds, const SkPaint* paint, const SkImageFilter* backdrop,
-             const SkImage* clipMask, const SkMatrix* clipMatrix, SaveLayerFlags saveLayerFlags)
-
- -Experimental. Not ready for general use. - -Sets fBounds, fPaint, fBackdrop, fClipMask, fClipMatrix, and fSaveLayerFlags. -clipMatrix uses Color_Alpha channel of image, transformed by clipMatrix, to clip -Layer when drawn to Canvas. - -Implementation is not complete; has no effect if Device is GPU-backed. - -### Parameters - - - - - - - - - - - - - - - - - - - -
boundsLayer dimensions; may be nullptr
paintgraphics state applied to Layer when overlaying prior -Layer; may be nullptr -
backdropprior Layer copied with Image_Filter; -may be nullptr -
clipMaskclip applied to Layer; may be nullptr
clipMatrixmatrix applied to clipMask; may be nullptr to use -identity matrix -
saveLayerFlagsSaveLayerRec options to modify Layer
- -### Return Value - -SaveLayerRec fully specified - -### See Also - -save restore saveLayer saveLayerPreserveLCDTextRequests saveLayerAlpha - --- @@ -2676,30 +2546,6 @@ visible as a thin pair of lines through the righ clipRRect clipPath clipRegion - - ---- - -
-void androidFramework_setDeviceClipRestriction(const SkIRect& rect)
-
- -Sets the maximum clip rectangle, which can be set by clipRect, clipRRect and -clipPath and intersect the current clip with the specified rect. -The maximum clip affects only future clipping operations; it is not retroactive. -The clip restriction is not recorded in pictures. - -Pass an empty rect to disable maximum clip. - -Private: This private API is for use by Android framework only. - -### Parameters - - - - -# - --- @@ -2907,18 +2753,6 @@ is set to SkPath::clipRectclipRRectclipRegion - - ---- - -
-void setAllowSimplifyClip(bool allow)
-
- -Experimental. For testing only. - -Set to simplify clip stack using PathOps. - --- @@ -3275,7 +3109,7 @@ any cached data is deleted when owning flush()SkSurface::prepareForExternalIOGrContext::abandonContext +flush()GrContext::abandonContext @@ -5130,144 +4964,6 @@ are scaled if needed to take up the remaining space; the center is transparent. drawBitmapLatticedrawImagedrawImageNineLattice - - ---- - -
-    enum QuadAAFlags : unsigned {
-        kLeft_QuadAAFlag = 0b0001,
-        kTop_QuadAAFlag = 0b0010,
-        kRight_QuadAAFlag = 0b0100,
-        kBottom_QuadAAFlag = 0b1000,
-        kNone_QuadAAFlags = 0b0000,
-        kAll_QuadAAFlags = 0b1111,
-    };
-
- -Private: Do not use. - -### Constants - -
rectmaximum allowed clip in device coordinates
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ConstValueDescription
SkCanvas::kLeft_QuadAAFlag1 -antialias the left edge
SkCanvas::kTop_QuadAAFlag2 -antialias the top edge
SkCanvas::kRight_QuadAAFlag4 -antialias the right edge
SkCanvas::kBottom_QuadAAFlag8 -antialias the bottom edge
SkCanvas::kNone_QuadAAFlags0 -antialias none of the edges
SkCanvas::kAll_QuadAAFlags15 -antialias all of the edges
- - - ---- - -
-    struct ImageSetEntry {
-        sk_spSkImage> fImage;
-        SkRect fSrcRect;
-        SkRect fDstRect;
-        unsigned fAAFlags;
-
-    };
-
- -Private: Do not use. - - - - - - - - - - - - - - - - - - - - - - - - -
TypeMemberDescription
SkImage*fImage -image to draw
SkRectfSrcRect -image src rectangle
SkRectfDstRect -local space rectangle
unsignedfAAFlags -antialiasing flags
- - - ---- - -
-void experimental_DrawImageSetV0(const ImageSetEntry imageSet[], int cnt, float alpha,
-                                 SkFilterQuality quality, SkBlendMode mode) ;
-
- -Private: Do not use. - -Draws a set of images. Do not use this method. - -### Parameters - - - - - - - - - - - - - - - - -
imageSetimages
cntnumber of images
alphaalpha
qualityfilter quality
modeblend mode
- diff --git a/site/user/api/SkImage_Reference.md b/site/user/api/SkImage_Reference.md index e47886cdc4..38927de570 100644 --- a/site/user/api/SkImage_Reference.md +++ b/site/user/api/SkImage_Reference.md @@ -126,7 +126,7 @@ public: const SkMatrix* localMatrix = nullptr) const; sk_sp<SkShader> makeShader(const SkMatrix* localMatrix = nullptr) const; bool peekPixels(SkPixmap* pixmap) const; - GrTexture* getTexture() const; + GrTexture* getTexture() const; bool isTextureBacked() const; bool isValid(GrContext* context) const; GrBackendTexture getBackendTexture(bool flushPendingGrContextIO, @@ -162,12 +162,12 @@ public: GrBackendTexture* backendTexture, BackendTextureReleaseProc* backendTextureReleaseProc); - enum LegacyBitmapMode { - kRO_LegacyBitmapMode, + enum LegacyBitmapMode { + kRO_LegacyBitmapMode, }; - bool asLegacyBitmap(SkBitmap* bitmap, - LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const; + bool asLegacyBitmap(SkBitmap* bitmap, + LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const; bool isLazyGenerated() const; sk_sp<SkImage> makeColorSpace(sk_sp<SkColorSpace> target) const; }; @@ -1834,16 +1834,6 @@ true if SkImage has direct access to pix readPixels - - ---- - -
-GrTexture* getTexture() const
-
- -Deprecated. - --- @@ -2547,67 +2537,6 @@ true if back-end texture was created MakeFromTexture makeTextureImage - - ---- - -To be deprecated soon. - -
-    enum LegacyBitmapMode {
-        kRO_LegacyBitmapMode,
-    };
-
- -### Constants - - - - - - - - - - -
ConstValueDescription
SkImage::kRO_LegacyBitmapMode0 -returned bitmap is read-only and immutable
- - - ---- - -
-bool asLegacyBitmap(SkBitmap* bitmap, LegacyBitmapMode legacyBitmapMode = kRO_LegacyBitmapMode) const
-
- -Creates raster SkBitmap with same pixels as SkImage. If legacyBitmapMode is -kRO_LegacyBitmapMode, returned bitmap is read-only and immutable. -Returns true if SkBitmap is stored in bitmap. Returns false and resets bitmap if -SkBitmap write did not succeed. - -### Parameters - - - - - - - -
bitmapstorage for legacy SkBitmap
legacyBitmapModeto be deprecated
- -### Return Value - -true if SkBitmap was created - -### Example - -
- -### See Also - -MakeRasterData makeRasterImage makeNonTextureImage - --- diff --git a/site/user/api/SkPaint_Reference.md b/site/user/api/SkPaint_Reference.md index 60247fe7fe..0383d5a711 100644 --- a/site/user/api/SkPaint_Reference.md +++ b/site/user/api/SkPaint_Reference.md @@ -20,16 +20,16 @@ public: uint32_t getHash() const; void reset(); - enum Hinting : uint8_t { - kNo_Hinting = 0, - kSlight_Hinting = 1, - kNormal_Hinting = 2, - kFull_Hinting = 3, + enum Hinting : uint8_t { + kNo_Hinting = 0, + kSlight_Hinting = 1, + kNormal_Hinting = 2, + kFull_Hinting = 3, }; void setHinting(SkFontHinting hintingLevel); - Hinting getHinting() const; - void setHinting(Hinting h); + Hinting getHinting() const; + void setHinting(Hinting h); SkFontHinting getHinting() const; enum Flags { @@ -44,9 +44,9 @@ public: kAllFlags = 0xFFFF, }; - enum ReserveFlags { - kUnderlineText_ReserveFlag = 0x08, - kStrikeThruText_ReserveFlag = 0x10, + enum ReserveFlags { + kUnderlineText_ReserveFlag = 0x08, + kStrikeThruText_ReserveFlag = 0x10, }; uint32_t getFlags() const; @@ -142,9 +142,9 @@ public: void setImageFilter(sk_sp<SkImageFilter> imageFilter); SkDrawLooper* getDrawLooper() const; sk_sp<SkDrawLooper> refDrawLooper() const; - SkDrawLooper* getLooper() const; + SkDrawLooper* getLooper() const; void setDrawLooper(sk_sp<SkDrawLooper> drawLooper); - void setLooper(sk_sp<SkDrawLooper> drawLooper); + void setLooper(sk_sp<SkDrawLooper> drawLooper); SkScalar getTextSize() const; void setTextSize(SkScalar textSize); SkScalar getTextScaleX() const; @@ -191,11 +191,11 @@ public: SkScalar* intervals) const; SkRect getFontBounds() const; bool nothingToDraw() const; - bool canComputeFastBounds() const; - const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const; - const SkRect& computeFastStrokeBounds(const SkRect& orig, + bool canComputeFastBounds() const; + const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const; + const SkRect& computeFastStrokeBounds(const SkRect& orig, SkRect* storage) const; - const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, + const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, Style style) const; }; @@ -250,7 +250,7 @@ Constructs Paint with default values. | Font_Embedded_Bitmaps | false | | Automatic_Hinting | false | | Full_Hinting_Spacing | false | -| Hinting | SkFontHinting::kNormal | +| Hinting | SkFontHinting::kNormal | | Image_Filter | nullptr | | LCD_Text | false | | Linear_Text | false | @@ -595,59 +595,6 @@ paint1.getHash() == paint2.getHash() - - ---- - -
-    enum Hinting : uint8_t {
-        kNo_Hinting = 0,
-        kSlight_Hinting = 1,
-        kNormal_Hinting = 2,
-        kFull_Hinting = 3,
-    };
-
- -### Constants - - - - - - - - - - - - - - - - - - - - - - - - - -
ConstValueDescription
SkPaint::kNo_Hinting0 -Deprecated. - -
SkPaint::kSlight_Hinting1 -Deprecated. - -
SkPaint::kNormal_Hinting2 -Deprecated. - -
SkPaint::kFull_Hinting3 -Deprecated. - -
- --- @@ -685,32 +632,28 @@ paint1 == paint2 --- 
-Hinting getHinting() const
+SkFontHinting getHinting() const
Returns level of glyph outline adjustment. ### Return Value -one of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting +one of: SkFontHinting::kNone, SkFontHinting::kSlight, SkFontHinting::kNormal, - +SkFontHinting::kFull ---- +### Example -
-void setHinting(Hinting h)
-
+
-Sets level of glyph outline adjustment. -Does not check for valid values of h. +#### Example Output -### Parameters +~~~~ +SkFontHinting::kNormal == paint.getHinting() +~~~~ - - - -
hone of: kNo_Hinting, kSlight_Hinting, kNormal_Hinting, kFull_Hinting
+
@@ -802,45 +745,6 @@ mask of all Flags, including private flags and flag Flags default to all flags clear, disabling the associated feature. - - ---- - -To be deprecated soon. - -Only valid for Android framework. - -
-    enum ReserveFlags {
-        kUnderlineText_ReserveFlag = 0x08,
-        kStrikeThruText_ReserveFlag = 0x10,
-    };
-
- -### Constants - - - - - - - - - - - - - - - -
ConstValueDescription
SkPaint::kUnderlineText_ReserveFlag0x0008 -To be deprecated soon. - -
SkPaint::kStrikeThruText_ReserveFlag0x0010 -To be deprecated soon. - -
- --- @@ -1127,8 +1031,8 @@ When Subpixel_Text is enabled, the comma Linear_Text selects whether text is rendered as a Glyph or as a Path. -If kLinearText_Flag is set, it has the same effect as setting Hinting to SkFontHinting::kNormal. -If kLinearText_Flag is clear, it is the same as setting Hinting to SkFontHinting::kNone. +If kLinearText_Flag is set, it has the same effect as setting Hinting to SkFontHinting::kNormal. +If kLinearText_Flag is clear, it is the same as setting Hinting to SkFontHinting::kNone. @@ -1152,7 +1056,7 @@ Equivalent to getFlags() masked with setLinearText Hinting +setLinearText Hinting @@ -1181,7 +1085,7 @@ Clears kLinearText_Flag if isLinearText Hinting +isLinearText Hinting @@ -1424,9 +1328,9 @@ paint1 == paint2 -If Hinting is set to SkFontHinting::kNormal or SkFontHinting::kFull, Automatic_Hinting +If Hinting is set to SkFontHinting::kNormal or SkFontHinting::kFull, Automatic_Hinting instructs the Font_Manager to always hint Glyphs. -Automatic_Hinting has no effect if Hinting is set to SkFontHinting::kNone or +Automatic_Hinting has no effect if Hinting is set to SkFontHinting::kNone or SkFontHinting::kSlight. Automatic_Hinting only affects platforms that use FreeType as the Font_Manager. @@ -1439,7 +1343,7 @@ instructs the Font_Manager to always hint isAutohinted() const -Returns true if SkPaint::Hinting is set to SkFontHinting::kNormal or +Returns true if SkPaint::Hinting is set to SkFontHinting::kNormal or SkFontHinting::kFull, and if platform uses FreeType as the font manager. If true, instructs the font manager to always hint glyphs. @@ -1464,7 +1368,7 @@ paint.isAutohinted() == !!(paint.getFlags() & SkPaint::kAutoHinting_Flag) ### See Also -setAutohinted Hinting +setAutohinted Hinting @@ -1475,9 +1379,9 @@ void setAutohinted(bool useAutohinter) Sets whether to always hint glyphs. -If SkPaint::Hinting is set to SkFontHinting::kNormal or SkFontHinting::kFull +If SkPaint::Hinting is set to SkFontHinting::kNormal or SkFontHinting::kFull and useAutohinter is set, instructs the font manager to always hint glyphs. -auto-hinting has no effect if SkPaint::Hinting is set to SkFontHinting::kNone or +auto-hinting has no effect if SkPaint::Hinting is set to SkFontHinting::kNone or SkFontHinting::kSlight. Only affects platforms that use FreeType as the font manager. @@ -1498,7 +1402,7 @@ Clears kAutoHinting_Flag if isAutohinted Hinting +isAutohinted Hinting @@ -1585,7 +1489,7 @@ paint1 == paint2 -if Hinting is set to SkFontHinting::kFull, Full_Hinting_Spacing adjusts the character +if Hinting is set to SkFontHinting::kFull, Full_Hinting_Spacing adjusts the character spacing by the difference of the hinted and unhinted Left_Side_Bearing and Right_Side_Bearing. Full_Hinting_Spacing only applies to platforms that use FreeType as their Font_Engine. @@ -3502,22 +3406,12 @@ draw looper unique: false - - ---- - -
-SkDrawLooper* getLooper() const
-
- -Deprecated. - --- 
-void setDrawLooper(sk_sp<SkDrawLooper> drawLooper)
+void setDrawLooper(sk_sp<SkDrawLooper> drawLooper)
Sets SkDrawLooper to drawLooper, decreasing SkRefCnt of the previous @@ -3537,16 +3431,6 @@ Increments drawLooper - ---- - -
-void setLooper(sk_sp<SkDrawLooper> drawLooper)
-
- -Deprecated. - --- @@ -4557,7 +4441,7 @@ number of intersections; may be zero Returns the union of bounds of all glyphs. Returned dimensions are computed by font manager from font data, -ignoring SkPaint::Hinting. Includes font metrics, but not fake bold or SkPathEffect. +ignoring SkPaint::Hinting. Includes font metrics, but not fake bold or SkPathEffect. If text size is large, text scale is one, and text skew is zero, returns the bounds as: @@ -4613,129 +4497,5 @@ alpha 0 nothing to draw: true - - -Private: To be made private. - -Fast_Bounds functions conservatively outset a drawing bounds by additional area -Paint may draw to. - - - ---- - -
-bool canComputeFastBounds() const
-
- -Private: (to be made private) - -Returns true if Paint does not include elements requiring extensive computation -to compute Device bounds of drawn geometry. For instance, Paint with Path_Effect -always returns false. - -### Return Value - -true if Paint allows for fast computation of bounds - - - ---- - -
-const SkRect& computeFastBounds(const SkRect& orig, SkRect* storage) const
-
- -Private: (to be made private) - -Only call if canComputeFastBounds returned true. This takes a -raw rectangle, the raw bounds of a shape; and adjusts it for stylistic -effects in the paint, such as stroking. If needed, it uses the storage -parameter. It returns the adjusted bounds that can then be used -for SkCanvas::quickReject tests. - -The returned Rect will either be orig or storage, thus the caller -should not rely on storage being set to the result, but should always -use the returned value. It is legal for orig and storage to be the same -Rect. - -Private: For example: - if (!path.isInverseFillType() && paint.canComputeFastBounds()) { - SkRect storage; - if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) { - return; // do not draw the path - } - } - // draw the path - -### Parameters - - - - - - - -
origgeometry modified by Paint when drawn
storagecomputed bounds of geometry; may not be nullptr
- -### Return Value - -fast computed bounds - - - ---- - -
-const SkRect& computeFastStrokeBounds(const SkRect& orig, SkRect* storage) const
-
- -Private: (to be made private) - -### Parameters - - - - - - - -
origgeometry modified by Paint when drawn
storagecomputed bounds of geometry
- -### Return Value - -fast computed bounds - - - ---- - -
-const SkRect& doComputeFastBounds(const SkRect& orig, SkRect* storage, Style style) const
-
- -Private: (to be made private) - -Computes the bounds, overriding the Paint Style. This can be used to -account for additional width required by stroking orig, without -altering Style set to fill. - -### Parameters - - - - - - - - - - -
origgeometry modified by Paint when drawn
storagecomputed bounds of geometry
styleoverrides Style
- -### Return Value - -fast computed bounds - diff --git a/site/user/api/SkPath_Reference.md b/site/user/api/SkPath_Reference.md index c378adc9b6..830f168850 100644 --- a/site/user/api/SkPath_Reference.md +++ b/site/user/api/SkPath_Reference.md @@ -200,7 +200,7 @@ public: uint32_t getGenerationID() const; bool isValid() const; bool isValid() const; - bool pathRefIsValid() const; + bool pathRefIsValid() const; }; @@ -4997,16 +4997,6 @@ array dimensions. true if SkPath data is consistent - - ---- - -
-bool pathRefIsValid() const
-
- -To be deprecated soon. - --- diff --git a/site/user/api/SkPixmap_Reference.md b/site/user/api/SkPixmap_Reference.md index 17c19f879c..d917f3a20a 100644 --- a/site/user/api/SkPixmap_Reference.md +++ b/site/user/api/SkPixmap_Reference.md @@ -273,22 +273,12 @@ is not unique Color_Space SkImageInfo::makeColorSpace - - ---- - -
-bool reset(const SkMask& mask)
-
- -To be deprecated soon. - --- 
-bool extractSubset(SkPixmap* subset, const SkIRect& area) const
+bool extractSubset(SkPixmap* subset, const SkIRect& area) const
Sets subset width, height, pixel address to intersection of SkPixmap with area, diff --git a/site/user/api/SkRect_Reference.md b/site/user/api/SkRect_Reference.md index fced84f13a..f18f876ef9 100644 --- a/site/user/api/SkRect_Reference.md +++ b/site/user/api/SkRect_Reference.md @@ -994,15 +994,13 @@ test with NaN is not equal to itself void toQuad(SkPoint quad[4]) const -Returns four points in quad that enclose Rect ordered as: top-left, top-right, +Returns four points in quad that enclose SkRect ordered as: top-left, top-right, bottom-right, bottom-left. -Private: Consider adding param to control whether quad is clockwise or counterclockwise. - ### Parameters - +
quadstorage for corners of Rectstorage for corners of SkRect
diff --git a/site/user/api/SkRegion_Reference.md b/site/user/api/SkRegion_Reference.md index 12b28c2215..f766134201 100644 --- a/site/user/api/SkRegion_Reference.md +++ b/site/user/api/SkRegion_Reference.md @@ -69,7 +69,7 @@ public: bool op(const SkIRect& rect, const SkRegion& rgn, Op op); bool op(const SkRegion& rgn, const SkIRect& rect, Op op); bool op(const SkRegion& rgna, const SkRegion& rgnb, Op op); - char* toString(); + char* toString(); class Iterator { public: @@ -2126,20 +2126,6 @@ false if result is empty setRects Op - - ---- - -
-char* toString()
-
- -Private: Android framework only. - -### Return Value - -string representation of Region - --- diff --git a/site/user/api/SkSurface_Reference.md b/site/user/api/SkSurface_Reference.md index 39d4d74f56..8870379c3b 100644 --- a/site/user/api/SkSurface_Reference.md +++ b/site/user/api/SkSurface_Reference.md @@ -72,11 +72,11 @@ public: kDiscardWrite_BackendHandleAccess, }; - static const BackendHandleAccess kFlushRead_TextureHandleAccess = + static const BackendHandleAccess kFlushRead_TextureHandleAccess = kFlushRead_BackendHandleAccess; - static const BackendHandleAccess kFlushWrite_TextureHandleAccess = + static const BackendHandleAccess kFlushWrite_TextureHandleAccess = kFlushWrite_BackendHandleAccess; - static const BackendHandleAccess kDiscardWrite_TextureHandleAccess = + static const BackendHandleAccess kDiscardWrite_TextureHandleAccess = kDiscardWrite_BackendHandleAccess; GrBackendTexture getBackendTexture(BackendHandleAccess backendHandleAccess); GrBackendRenderTarget getBackendRenderTarget(BackendHandleAccess backendHandleAccess); @@ -92,7 +92,7 @@ public: void writePixels(const SkPixmap& src, int dstX, int dstY); void writePixels(const SkBitmap& src, int dstX, int dstY); const SkSurfaceProps& props() const; - void prepareForExternalIO(); + void prepareForExternalIO(); void flush(); GrSemaphoresSubmitted flushAndSignalSemaphores(int numSemaphores, GrBackendSemaphore signalSemaphores[]); @@ -1080,12 +1080,8 @@ If a snapshot has been generated, this copies the notifyContentWillChange(ContentChangeMode mode) -Notifies that Surface contents will be changed by code outside of Skia. -Subsequent calls to generationID return a different value. - -mode is normally passed as kRetain_ContentChangeMode. - -Private: Can we deprecate this? +Notifies that SkSurface contents will be changed by code outside of Skia. +Subsequent calls to generationID() return a different value. ### Parameters @@ -1113,11 +1109,11 @@ Private: Can we deprecate this? kDiscardWrite_BackendHandleAccess, }; - static const BackendHandleAccess kFlushRead_TextureHandleAccess = + static const BackendHandleAccess kFlushRead_TextureHandleAccess = kFlushRead_BackendHandleAccess; - static const BackendHandleAccess kFlushWrite_TextureHandleAccess = + static const BackendHandleAccess kFlushWrite_TextureHandleAccess = kFlushWrite_BackendHandleAccess; - static const BackendHandleAccess kDiscardWrite_TextureHandleAccess = + static const BackendHandleAccess kDiscardWrite_TextureHandleAccess = kDiscardWrite_BackendHandleAccess; @@ -1146,30 +1142,6 @@ Caller may write to the back-end object. 2 Caller must overwrite the entire back-end object. - - - - SkSurface::kFlushRead_TextureHandleAccess - 0 - -Deprecated. - - - - - SkSurface::kFlushWrite_TextureHandleAccess - 1 - -Deprecated. - - - - - SkSurface::kDiscardWrite_TextureHandleAccess - 2 - -Deprecated. - @@ -1701,16 +1673,6 @@ surf.props(): kRGB_H_SkPixelGeometry SkSurfaceProps - - ---- - -
-void prepareForExternalIO()
-
- -To be deprecated soon. - diff --git a/site/user/api/SkTextBlobBuilder_Reference.md b/site/user/api/SkTextBlobBuilder_Reference.md index 3de63a62ec..006630b04c 100644 --- a/site/user/api/SkTextBlobBuilder_Reference.md +++ b/site/user/api/SkTextBlobBuilder_Reference.md @@ -334,35 +334,3 @@ writable glyph buffer and allocRunPosH allocRun - - ---- - -
-const RunBuffer& allocRun(const SkPaint& font, int count, SkScalar x, SkScalar y,
-                          const SkRect* bounds = nullptr)
-
- -Deprecated. - - - ---- - -
-const RunBuffer& allocRunPosH(const SkPaint& font, int count, SkScalar y,
-                              const SkRect* bounds = nullptr)
-
- -Deprecated. - - - ---- - -
-const RunBuffer& allocRunPos(const SkPaint& font, int count, const SkRect* bounds = nullptr)
-
- -Deprecated. - diff --git a/site/user/api/catalog.htm b/site/user/api/catalog.htm index b8753321fa..c6fe099917 100644 --- a/site/user/api/catalog.htm +++ b/site/user/api/catalog.htm @@ -1492,8 +1492,8 @@ "stdout": "(SkPaint::kAntiAlias_Flag & paint.getFlags()) != 0\\n" }, "SkPaint_getFontBounds": { - "code": "void draw(SkCanvas* canvas) {\n SkPaint paint;\n SkPaint::FontMetrics fm;\n paint.getFontMetrics(&fm);\n SkRect fb = paint.getFontBounds();\n SkDebugf(\"metrics bounds = { %g, %g, %g, %g }\\n\", fm.fXMin, fm.fTop, fm.fXMax, fm.fBottom );\n SkDebugf(\"font bounds = { %g, %g, %g, %g }\\n\", fb.fLeft, fb.fTop, fb.fRight, fm.fBottom );\n}", - "hash": "facaddeec7943bc491988e345e27e65f", + "code": "void draw(SkCanvas* canvas) {\n SkPaint paint;\n SkFontMetrics fm;\n paint.getFontMetrics(&fm);\n SkRect fb = paint.getFontBounds();\n SkDebugf(\"metrics bounds = { %g, %g, %g, %g }\\n\", fm.fXMin, fm.fTop, fm.fXMax, fm.fBottom );\n SkDebugf(\"font bounds = { %g, %g, %g, %g }\\n\", fb.fLeft, fb.fTop, fb.fRight, fm.fBottom );\n}", + "hash": "f29d005a75efd4746c6744004a0cb421", "file": "SkPaint_Reference", "name": "SkPaint::getFontBounds", "stdout": "metrics bounds = { -12.2461, -14.7891, 21.5215, 5.55469 }\\nfont bounds = { -12.2461, -14.7891, 21.5215, 5.55469 }\\n" @@ -1511,6 +1511,13 @@ "file": "SkPaint_Reference", "name": "SkPaint::getHash", "stdout": "paint1 == paint2\\npaint1.getHash() == paint2.getHash()\\n" + }, + "SkPaint_getHinting": { + "code": "void draw(SkCanvas* canvas) {\n SkPaint paint;\n SkDebugf(\"SkFontHinting::kNormal %c= paint.getHinting()\\n\",\n SkFontHinting::kNormal == paint.getHinting() ? '=' : ':');\n}", + "hash": "b56b70c7ea2453c41bfa58b626953bed", + "file": "SkPaint_Reference", + "name": "SkPaint::getHinting", + "stdout": "SkFontHinting::kNormal == paint.getHinting()\\n" }, "SkPaint_getImageFilter": { "code": "#include \"SkBlurImageFilter.h\"\n\nvoid draw(SkCanvas* canvas) {\n SkPaint paint;\n SkDebugf(\"nullptr %c= image filter\\n\", paint.getImageFilter() ? '!' : '=');\n paint.setImageFilter(SkBlurImageFilter::Make(kOuter_SkBlurStyle, 3, nullptr, nullptr));\n SkDebugf(\"nullptr %c= image filter\\n\", paint.getImageFilter() ? '!' : '=');\n}\n", @@ -6091,14 +6098,6 @@ "hash": "1b9f1f05026ceb14ccb6926a13cdaa83", "file": "SkImage_Reference", "name": "SkImage::alphaType" -}, - "SkImage_asLegacyBitmap": { - "code": "void draw(SkCanvas* canvas) {\n SkBitmap bitImage;\n if (image->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) {\n canvas->drawBitmap(bitImage, 0, 0);\n }\n GrContext* grContext = canvas->getGrContext();\n if (!grContext) {\n return;\n }\n sk_sp textureImage(SkImage::MakeFromTexture(grContext, backEndTexture,\n kTopLeft_GrSurfaceOrigin, kRGBA_8888_SkColorType,\n kOpaque_SkAlphaType, nullptr));\n canvas->drawImage(textureImage, 45, 45);\n if (textureImage->asLegacyBitmap(&bitImage, SkImage::kRO_LegacyBitmapMode)) {\n canvas->drawBitmap(bitImage, 90, 90);\n }\n}", - "width": 256, - "height": 256, - "hash": "78374702fa113076ddc6070053ab5cd4", - "file": "SkImage_Reference", - "name": "SkImage::asLegacyBitmap" }, "SkImage_bounds": { "code": "void draw(SkCanvas* canvas) {\n SkIRect bounds = image->bounds();\n for (int x : { 0, bounds.width() } ) {\n for (int y : { 0, bounds.height() } ) {\n canvas->drawImage(image, x, y);\n }\n }\n}", @@ -7035,14 +7034,6 @@ "hash": "882e8e0103048009a25cfc20400492f7", "file": "SkMemoryStream_Reference", "name": "SkMemoryStream::setMemory" -}, - "SkMemoryStream_setMemoryOwned": { - "code": "void draw(SkCanvas* canvas) {\n // incomplete\n}", - "width": 256, - "height": 256, - "hash": "882e8e0103048009a25cfc20400492f7", - "file": "SkMemoryStream_Reference", - "name": "SkMemoryStream::setMemoryOwned" }, "SkMemoryStream_skipToAlign4": { "code": "void draw(SkCanvas* canvas) {\n // incomplete\n}", diff --git a/site/user/api/usingBookmaker.md b/site/user/api/usingBookmaker.md index cb8c1f96d5..5aaa9202d7 100644 --- a/site/user/api/usingBookmaker.md +++ b/site/user/api/usingBookmaker.md @@ -85,22 +85,9 @@ To fix this, edit the docs file corresponding to the changed include file. For instance, if the change was made to SkIRect, edit docs/SkIRect_Reference.bmh. Checking in the edited docs/SkIRect_Reference.bmh will fix the bot. -If the interface is deprecated, but still present in the interface, mark-up the -documentation to be deprecated as well. - -
-#Method void someMethodThatIsNowDeprecated()
-#Deprecated
-##
-
- -Use - -
-#Deprecated soon
-
- -if the change is soon to be deprecated. +If the interface is deprecated, private, or experimental, documentation is not +required. Put the word "Deprecated", "Private", or "Experimental"; upper or lower +case, in a comment just before the symbol to be ignored. If Housekeeper-Nightly-Bookmaker bot is red, one of several things may have gone wrong: diff --git a/tools/bookmaker/bmhParser.cpp b/tools/bookmaker/bmhParser.cpp index a0a46c30e4..1f99c729b3 100644 --- a/tools/bookmaker/bmhParser.cpp +++ b/tools/bookmaker/bmhParser.cpp @@ -46,14 +46,12 @@ BmhParser::MarkProps BmhParser::kMarkProps[] = { , { "", MarkType::kComment, R_N, E_N, 0 } , { "Const", MarkType::kConst, R_Y, E_O, M_E | M_CSST } , { "Define", MarkType::kDefine, R_O, E_Y, M_ST } -, { "Deprecated", MarkType::kDeprecated, R_Y, E_N, M_CS | M_MDCM | M_E } , { "Description", MarkType::kDescription, R_Y, E_N, M(Example) | M(NoExample) } , { "Details", MarkType::kDetails, R_N, E_N, M(Const) } , { "Duration", MarkType::kDuration, R_N, E_N, M(Example) | M(NoExample) } , { "Enum", MarkType::kEnum, R_Y, E_O, M_CSST } , { "EnumClass", MarkType::kEnumClass, R_Y, E_O, M_CSST } , { "Example", MarkType::kExample, R_O, E_N, M_CSST | M_E | M_MD | M(Const) } -, { "Experimental", MarkType::kExperimental, R_Y, E_N, M_CS | M_MDCM | M_E } , { "External", MarkType::kExternal, R_Y, E_N, 0 } , { "File", MarkType::kFile, R_Y, E_N, M(Topic) } , { "Filter", MarkType::kFilter, R_N, E_N, M(Subtopic) | M(Code) } @@ -81,7 +79,6 @@ BmhParser::MarkProps BmhParser::kMarkProps[] = { , { "", MarkType::kPhraseRef, R_N, E_N, 0 } , { "Platform", MarkType::kPlatform, R_N, E_N, M(Example) | M(NoExample) } , { "Populate", MarkType::kPopulate, R_N, E_N, M(Code) | M(Method) } -, { "Private", MarkType::kPrivate, R_N, E_N, M_CSST | M_MDCM | M_E } , { "Return", MarkType::kReturn, R_Y, E_N, M(Method) } , { "", MarkType::kRow, R_Y, E_N, M(Table) | M(List) } , { "SeeAlso", MarkType::kSeeAlso, R_C, E_N, M_CSST | M_E | M_MD | M(Typedef) } @@ -195,10 +192,7 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy if (MarkType::kExample == child->fMarkType) { hasExample = Exemplary::kYes; } - hasExcluder |= MarkType::kPrivate == child->fMarkType - || MarkType::kDeprecated == child->fMarkType - || MarkType::kExperimental == child->fMarkType - || MarkType::kNoExample == child->fMarkType; + hasExcluder |= MarkType::kNoExample == child->fMarkType; } if (kMarkProps[(int) markType].fExemplary != hasExample && kMarkProps[(int) markType].fExemplary != Exemplary::kOptional) { @@ -452,7 +446,6 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy case MarkType::kFunction: case MarkType::kLegend: case MarkType::kList: - case MarkType::kPrivate: case MarkType::kTable: if (hasEnd) { definition = fParent; @@ -504,10 +497,8 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy // always treated as one-liners (can't detect misuse easily) case MarkType::kAnchor: case MarkType::kBug: - case MarkType::kDeprecated: case MarkType::kDetails: case MarkType::kDuration: - case MarkType::kExperimental: case MarkType::kFilter: case MarkType::kHeight: case MarkType::kIllustration: @@ -542,20 +533,7 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy this->parseHashAnchor(definition); } else if (MarkType::kLine == markType) { this->parseHashLine(definition); - } else if (IncompleteAllowed(markType)) { - this->skipSpace(); - fParent->fDeprecated = true; - fParent->fDetails = - this->skipExact("soon") ? Definition::Details::kSoonToBe_Deprecated : - this->skipExact("testing") ? Definition::Details::kTestingOnly_Experiment : - this->skipExact("do not use") ? Definition::Details::kDoNotUse_Experiment : - this->skipExact("not ready") ? Definition::Details::kNotReady_Experiment : - Definition::Details::kNone; - this->skipSpace(); - if ('\n' != this->peek()) { - return this->reportError("unexpected text after #Deprecated"); - } - } + } break; case MarkType::kExternal: (void) this->collectExternals(); // FIXME: detect errors in external defs? @@ -2126,7 +2104,6 @@ vector BmhParser::typeName(MarkType markType, bool* checkEnd) { case MarkType::kLegend: case MarkType::kList: case MarkType::kNoExample: - case MarkType::kPrivate: this->skipNoName(); break; case MarkType::kFormula: @@ -2136,10 +2113,8 @@ vector BmhParser::typeName(MarkType markType, bool* checkEnd) { case MarkType::kAlias: case MarkType::kAnchor: case MarkType::kBug: // fixme: expect number - case MarkType::kDeprecated: case MarkType::kDetails: case MarkType::kDuration: - case MarkType::kExperimental: case MarkType::kFile: case MarkType::kFilter: case MarkType::kHeight: @@ -2244,11 +2219,7 @@ string BmhParser::uniqueName(string base, MarkType markType) { for (auto& iter : fParent->fChildren) { if (markType == iter->fMarkType) { if (iter->fName == numBuilder) { - if (iter->fDeprecated) { - iter->fClone = true; - } else { - fCloned = true; - } + fCloned = true; numBuilder = builder + '_' + to_string(number); goto tryNext; } @@ -2301,14 +2272,8 @@ tryNext: ; } if (MarkType::kMethod == markType) { cloned->fCloned = true; - if (cloned->fDeprecated) { - cloned->fClone = true; - } else { - fCloned = true; - } - } else { - fCloned = true; } + fCloned = true; numBuilder = builder + '_' + to_string(number); } while (++number); return numBuilder; diff --git a/tools/bookmaker/bookmaker.h b/tools/bookmaker/bookmaker.h index 4fb65cabee..72e25039a2 100644 --- a/tools/bookmaker/bookmaker.h +++ b/tools/bookmaker/bookmaker.h @@ -109,14 +109,12 @@ enum class MarkType { kComment, kConst, kDefine, - kDeprecated, kDescription, kDetails, // used by #Const to specify #Subtopic details with examples and so on kDuration, kEnum, kEnumClass, kExample, - kExperimental, kExternal, kFile, kFilter, @@ -143,7 +141,6 @@ enum class MarkType { kPhraseRef, kPlatform, kPopulate, - kPrivate, kReturn, kRow, kSeeAlso, @@ -164,10 +161,6 @@ enum class MarkType { kWidth, }; -static inline bool IncompleteAllowed(MarkType markType) { - return MarkType::kDeprecated == markType || MarkType::kExperimental == markType; -} - enum { Last_MarkType = (int) MarkType::kWidth, }; diff --git a/tools/bookmaker/definition.cpp b/tools/bookmaker/definition.cpp index e6707f6c55..8055d698fb 100644 --- a/tools/bookmaker/definition.cpp +++ b/tools/bookmaker/definition.cpp @@ -468,11 +468,8 @@ bool Definition::checkMethod() const { } bool expectReturn = this->methodHasReturn(name, &methodParser); bool foundReturn = false; - bool foundException = false; bool foundPopulate = false; for (auto& child : fChildren) { - foundException |= MarkType::kDeprecated == child->fMarkType - || MarkType::kExperimental == child->fMarkType; foundPopulate |= MarkType::kPopulate == child->fMarkType; if (MarkType::kReturn != child->fMarkType) { if (MarkType::kParam == child->fMarkType) { @@ -488,7 +485,7 @@ bool Definition::checkMethod() const { } foundReturn = true; } - if (expectReturn && !foundReturn && !foundException && !foundPopulate) { + if (expectReturn && !foundReturn && !foundPopulate) { return methodParser.reportError("missing #Return marker"); } const char* paren = methodParser.strnchr('(', methodParser.fEnd); @@ -522,7 +519,7 @@ bool Definition::checkMethod() const { foundParam = true; } - if (!foundParam && !foundException && !foundPopulate) { + if (!foundParam && !foundPopulate) { return methodParser.reportError("no #Param found"); } if (')' == nextEnd[0]) { @@ -552,12 +549,6 @@ bool Definition::checkMethod() const { priorDef = child; continue; } - if (MarkType::kDeprecated == child->fMarkType) { - return true; - } - if (MarkType::kExperimental == child->fMarkType) { - return true; - } if (MarkType::kFormula == child->fMarkType) { continue; } @@ -576,9 +567,6 @@ bool Definition::checkMethod() const { if (MarkType::kPhraseRef == child->fMarkType) { continue; } - if (MarkType::kPrivate == child->fMarkType) { - return true; - } TextParser emptyCheck(fFileName, descStart, child->fStart, child->fLineCount); if (!emptyCheck.eof() && emptyCheck.skipWhiteSpace()) { descStart = emptyCheck.fChar; @@ -933,31 +921,6 @@ bool Definition::hasMatch(string name) const { return false; } -string Definition::incompleteMessage(DetailsType detailsType) const { - SkASSERT(!IncompleteAllowed(fMarkType)); - auto iter = std::find_if(fChildren.begin(), fChildren.end(), - [](const Definition* test) { return IncompleteAllowed(test->fMarkType); }); - SkASSERT(fChildren.end() != iter); - SkASSERT(Details::kNone == (*iter)->fDetails); - string message = MarkType::kExperimental == (*iter)->fMarkType ? - "Experimental." : "Deprecated."; - if (Details::kDoNotUse_Experiment == fDetails) { - message += " Do not use."; - } else if (Details::kNotReady_Experiment == fDetails) { - message += " Not ready for general use."; - } else if (Details::kSoonToBe_Deprecated == fDetails) { - message = "To be deprecated soon."; - } else if (Details::kTestingOnly_Experiment == fDetails) { - message += " For testing only."; - } - if (DetailsType::kPhrase == detailsType) { - message = message.substr(0, message.length() - 1); // remove trailing period - std::replace(message.begin(), message.end(), '.', ':'); - std::transform(message.begin(), message.end(), message.begin(), ::tolower); - } - return message; -} - bool Definition::isStructOrClass() const { if (MarkType::kStruct != fMarkType && MarkType::kClass != fMarkType) { return false; diff --git a/tools/bookmaker/definition.h b/tools/bookmaker/definition.h index 632135b77b..8aace77623 100644 --- a/tools/bookmaker/definition.h +++ b/tools/bookmaker/definition.h @@ -148,7 +148,6 @@ public: const Definition* hasChild(MarkType markType) const; bool hasMatch(string name) const; Definition* hasParam(string ref); - string incompleteMessage(DetailsType ) const; bool isClone() const { return fClone; } const Definition* iRootParent() const { @@ -253,12 +252,12 @@ public: char fMC = '#'; bool fClone = false; bool fCloned = false; - bool fDeprecated = false; bool fOperatorConst = false; bool fPrivate = false; Details fDetails = Details::kNone; bool fMemberStart = false; bool fAnonymous = false; + bool fUndocumented = false; // include symbol comment has deprecated, private, experimental mutable bool fVisited = false; }; diff --git a/tools/bookmaker/hackParser.cpp b/tools/bookmaker/hackParser.cpp index 03823a3f71..dcd834616d 100644 --- a/tools/bookmaker/hackParser.cpp +++ b/tools/bookmaker/hackParser.cpp @@ -73,10 +73,7 @@ void HackParser::replaceWithPop(const Definition* root) { || MarkType::kFormula == def->fMarkType || MarkType::kAnchor == def->fMarkType || MarkType::kList == def->fMarkType - || MarkType::kTable == def->fMarkType - || MarkType::kDeprecated == def->fMarkType - || MarkType::kExperimental == def->fMarkType - || MarkType::kPrivate == def->fMarkType; + || MarkType::kTable == def->fMarkType; } )) { continue; } diff --git a/tools/bookmaker/includeParser.cpp b/tools/bookmaker/includeParser.cpp index 523a3e808c..a9ec3db4d4 100644 --- a/tools/bookmaker/includeParser.cpp +++ b/tools/bookmaker/includeParser.cpp @@ -577,15 +577,15 @@ bool IncludeParser::checkForWord() { break; // these continue a # directive link case KeyWord::kElif: - case KeyWord::kElse: { + case KeyWord::kElse: this->popObject(); // pop elif if (Bracket::kPound != fParent->fBracket) { return this->reportError("expected preprocessor directive"); } this->popBracket(); // pop if poundDef->fParent = fParent; - this->addDefinition(poundDef); // push elif back - } break; + fParent = poundDef; // push elif back + break; // this ends a # directive link case KeyWord::kEndif: // FIXME : should this be calling popBracket() instead? @@ -644,6 +644,9 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { } } for (auto& classMapper : fIClassMap) { + if (classMapper.second.fUndocumented) { + continue; + } string className = classMapper.first; std::istringstream iss(className); string classStr; @@ -769,17 +772,17 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { def = root->find(withParens, RootDefinition::AllowParens::kNo); } if (!def) { - if (!root->fDeprecated) { + if (!token.fUndocumented) { SkDebugf("method missing from bmh: %s\n", fullName.c_str()); fFailed = true; } break; } + if (token.fUndocumented) { + break; + } if (def->crossCheck2(token)) { def->fVisited = true; - if (token.fDeprecated && !def->fDeprecated) { - fFailed = !def->reportError("expect bmh to be marked deprecated"); - } } else { SkDebugf("method differs from bmh: %s\n", fullName.c_str()); fFailed = true; @@ -818,7 +821,7 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { def = root->find(anonName, RootDefinition::AllowParens::kYes); } if (!def) { - if (!root->fDeprecated) { + if (!token.fUndocumented) { SkDebugf("enum missing from bmh: %s\n", fullName.c_str()); fFailed = true; } @@ -841,10 +844,8 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { } } if (!hasCode) { - if (!root->fDeprecated) { - SkDebugf("enum code missing from bmh: %s\n", fullName.c_str()); - fFailed = true; - } + SkDebugf("enum code missing from bmh: %s\n", fullName.c_str()); + fFailed = true; break; } if (!hasPopulate) { @@ -855,21 +856,22 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { fFailed = true; } } - for (auto& child : token.fChildren) { + for (auto& member : token.fTokens) { + if (MarkType::kMember != member.fMarkType) { + continue; + } string constName = MarkType::kEnumClass == token.fMarkType ? fullName : className; - constName += "::" + child->fName; + constName += "::" + member.fName; def = root->find(constName, RootDefinition::AllowParens::kYes); if (!def) { - string innerName = classMapper.first + "::" + child->fName; + string innerName = classMapper.first + "::" + member.fName; def = root->find(innerName, RootDefinition::AllowParens::kYes); } if (!def) { - if (string::npos == child->fName.find("Legacy_")) { - if (!root->fDeprecated) { - SkDebugf("const missing from bmh: %s\n", constName.c_str()); - fFailed = true; - } + if (!member.fUndocumented) { + SkDebugf("const missing from bmh: %s\n", constName.c_str()); + fFailed = true; } } else { def->fVisited = true; @@ -879,7 +881,7 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { case MarkType::kMember: if (def) { def->fVisited = true; - } else if (!root->fDeprecated) { + } else { SkDebugf("member missing from bmh: %s\n", fullName.c_str()); fFailed = true; } @@ -887,7 +889,7 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { case MarkType::kTypedef: if (def) { def->fVisited = true; - } else if (!root->fDeprecated) { + } else { SkDebugf("typedef missing from bmh: %s\n", fullName.c_str()); fFailed = true; } @@ -895,9 +897,11 @@ bool IncludeParser::crossCheck(BmhParser& bmhParser) { case MarkType::kConst: if (def) { def->fVisited = true; - } else if (!root->fDeprecated) { - SkDebugf("const missing from bmh: %s\n", fullName.c_str()); - fFailed = true; + } else { + if (!token.fUndocumented) { + SkDebugf("const missing from bmh: %s\n", fullName.c_str()); + fFailed = true; + } } break; default: @@ -966,6 +970,11 @@ IClassDefinition* IncludeParser::defineClass(const Definition& includeDef, MarkType::kStruct : MarkType::kClass; markupDef.fKeyWord = includeDef.fKeyWord; markupDef.fType = Definition::Type::kMark; + auto tokenIter = includeDef.fParent->fTokens.begin(); + SkASSERT(includeDef.fParentIndex > 0); + std::advance(tokenIter, includeDef.fParentIndex - 1); + const Definition* priorComment = &*tokenIter; + markupDef.fUndocumented = priorComment->fUndocumented; fParent = &markupDef; return &markupDef; } @@ -1625,6 +1634,9 @@ bool IncludeParser::dumpTokens(string skClassName, string globalFileName, long i if (this->isInternalName(token)) { continue; } + if (token.fUndocumented) { + continue; + } if (this->isConstructor(token, skClassName)) { hasConstructor = true; continue; @@ -1783,9 +1795,32 @@ string IncludeParser::elidedCodeBlock(const Definition& iDef) { return result; } +bool IncludeParser::findCommentAfter(const Definition& includeDef, Definition* markupDef) { + const Definition* parent = includeDef.fParent; + int index = includeDef.fParentIndex; + auto wordIter = parent->fTokens.begin(); + std::advance(wordIter, index); + SkASSERT(&*wordIter == &includeDef); + size_t commentLine = 0; + do { + wordIter = std::next(wordIter); + if (parent->fTokens.end() == wordIter) { + break; + } + commentLine = wordIter->fLineCount; + } while (Punctuation::kSemicolon != wordIter->fPunctuation); + wordIter = std::next(wordIter); + if (parent->fTokens.end() != wordIter && Bracket::kSlashSlash == wordIter->fBracket + && wordIter->fLineCount == commentLine) { + return this->parseComment(wordIter->fFileName, wordIter->fContentStart, + wordIter->fContentEnd, wordIter->fLineCount, markupDef, &markupDef->fUndocumented); + } + return true; +} + bool IncludeParser::findComments(const Definition& includeDef, Definition* markupDef) { // add comment preceding class, if any - const Definition* parent = includeDef.fParent; + Definition* parent = includeDef.fParent; int index = includeDef.fParentIndex; auto wordIter = parent->fTokens.begin(); std::advance(wordIter, index); @@ -1815,9 +1850,11 @@ bool IncludeParser::findComments(const Definition& includeDef, Definition* marku } while (commentIter != wordIter) { if (!this->parseComment(commentIter->fFileName, commentIter->fContentStart, - commentIter->fContentEnd, commentIter->fLineCount, markupDef)) { + commentIter->fContentEnd, commentIter->fLineCount, markupDef, + &markupDef->fUndocumented)) { return false; } + commentIter->fUndocumented = markupDef->fUndocumented; commentIter = std::next(commentIter); } return true; @@ -1854,10 +1891,6 @@ Definition* IncludeParser::findIncludeObject(const Definition& includeDef, MarkT } Definition* IncludeParser::findMethod(const Definition& bmhDef) { - if (std::any_of(bmhDef.fChildren.begin(), bmhDef.fChildren.end(), [](Definition* def) { - return MarkType::kDeprecated == def->fMarkType; } )) { - return nullptr; - } auto doubleColon = bmhDef.fName.rfind("::"); if (string::npos == doubleColon) { const auto& iGlobalMethod = fIFunctionMap.find(bmhDef.fName); @@ -1874,6 +1907,7 @@ Definition* IncludeParser::findMethod(const Definition& bmhDef) { const auto& iMethod = std::find_if(iTokens.begin(), iTokens.end(), [methodName](Definition& token) { return MarkType::kMethod == token.fMarkType + && !token.fUndocumented && (methodName == token.fName || methodName == token.fName + "()"); } ); if (iTokens.end() != iMethod) { @@ -1910,6 +1944,9 @@ Definition* IncludeParser::findMethod(const Definition& bmhDef) { if (MarkType::kMethod != token.fMarkType) { return false; } + if (token.fUndocumented) { + return false; + } TextParser parser(&token); const char* match = parser.strnstr(className.c_str(), parser.fEnd); if (!match) { @@ -2027,6 +2064,9 @@ bool IncludeParser::parseClass(Definition* includeDef, IsStruct isStruct) { if (!this->findComments(*includeDef, markupDef)) { return iter->reportError("find comments failed"); } + if (markupDef->fUndocumented) { + includeDef->fUndocumented = true; + } // if (1 != includeDef->fChildren.size()) { // return false; // fix me: SkCanvasClipVisitor isn't correctly parsed // } @@ -2107,10 +2147,29 @@ bool IncludeParser::parseClass(Definition* includeDef, IsStruct isStruct) { return true; } -bool IncludeParser::parseComment(string filename, const char* start, const char* end, - int lineCount, Definition* markupDef) { +bool IncludeParser::isUndocumentable(string filename, const char* start, const char* end, + int lineCount) { TextParser parser(filename, start, end, lineCount); + const vector skipWords = { "experimental", "deprecated", "private" }; + const vector butNot = { "to be deprecated", "may be deprecated" }; + const vector alsoNot = { "todo" }; + string match = parser.anyWord(skipWords, 0); + if ("" != match) { + if ("" == parser.anyWord(alsoNot, 0) + && ("deprecated" != match || "" == parser.anyWord(butNot, 2))) { + return true; + } + } + return false; +} + +bool IncludeParser::parseComment(string filename, const char* start, const char* end, + int lineCount, Definition* markupDef, bool* undocumentedPtr) { + if (this->isUndocumentable(filename, start, end, lineCount)) { + *undocumentedPtr = true; + } // parse doxygen if present + TextParser parser(filename, start, end, lineCount); if (parser.startsWith("**")) { parser.next(); parser.next(); @@ -2160,6 +2219,10 @@ bool IncludeParser::parseComment(string filename, const char* start, const char* return true; } +/* + find comment either in front of or after the const def and then extract if the + const is undocumented + */ bool IncludeParser::parseConst(Definition* child, Definition* markupDef) { if (!markupDef) { fGlobals.emplace_back(MarkType::kConst, child->fContentStart, child->fContentEnd, @@ -2170,7 +2233,14 @@ bool IncludeParser::parseConst(Definition* child, Definition* markupDef) { if (!this->findComments(*child, globalMarkupChild)) { return false; } - fIConstMap[globalUniqueName] = globalMarkupChild; + if (!this->findCommentAfter(*child, globalMarkupChild)) { + return false; + } + if (globalMarkupChild->fUndocumented) { + child->fUndocumented = true; + } else { + fIConstMap[globalUniqueName] = globalMarkupChild; + } return true; } markupDef->fTokens.emplace_back(MarkType::kConst, child->fContentStart, child->fContentEnd, @@ -2180,7 +2250,17 @@ bool IncludeParser::parseConst(Definition* child, Definition* markupDef) { markupChild->fTerminator = markupChild->fContentEnd; IClassDefinition& classDef = fIClassMap[markupDef->fName]; classDef.fConsts[child->fName] = markupChild; - fIConstMap[child->fName] = markupChild; + if (!this->findComments(*child, markupChild)) { + return false; + } + if (!this->findCommentAfter(*child, markupChild)) { + return false; + } + if (markupChild->fUndocumented) { + child->fUndocumented = true; + } else { + fIConstMap[child->fName] = markupChild; + } return true; } @@ -2245,7 +2325,9 @@ bool IncludeParser::parseDefine(Definition* child, Definition* markupDef) { if (!this->findComments(*child, globalMarkupChild)) { return false; } - fIDefineMap[globalUniqueName] = globalMarkupChild; + if (!globalMarkupChild->fUndocumented) { + fIDefineMap[globalUniqueName] = globalMarkupChild; + } for (Param param : params) { globalMarkupChild->fTokens.emplace_back(MarkType::kParam, param.fStart, param.fEnd, child->fLineCount, globalMarkupChild, '\0'); @@ -2264,28 +2346,29 @@ bool IncludeParser::parseDefine(Definition* child, Definition* markupDef) { if (!this->findComments(*child, markupChild)) { return false; } - classDef.fDefines[nameStr] = markupChild; - fIDefineMap[nameStr] = markupChild; + if (markupChild->fUndocumented) { + child->fUndocumented = true; + } else { + classDef.fDefines[nameStr] = markupChild; + fIDefineMap[nameStr] = markupChild; + } return true; } bool IncludeParser::parseEnum(Definition* child, Definition* markupDef) { - TextParser parser(child); - parser.skipToEndBracket('{'); - if (parser.eof()) { + if (!child->fTokens.size()) { return true; // if enum is a forward declaration, do nothing } - parser.next(); - string nameStr; - if (child->fTokens.size() > 0) { - auto token = child->fTokens.begin(); - if (Definition::Type::kKeyWord == token->fType && KeyWord::kClass == token->fKeyWord) { - token = token->fTokens.begin(); - } - if (Definition::Type::kWord == token->fType) { - nameStr += string(token->fStart, token->fContentEnd - token->fStart); - } + bool isEnumClass = false; + Definition* parent = child; + auto token = parent->fTokens.begin(); + if (Definition::Type::kKeyWord == token->fType && KeyWord::kClass == token->fKeyWord) { + isEnumClass = true; + parent = &*token; + token = parent->fTokens.begin(); } + SkASSERT(Definition::Type::kWord == token->fType); + string nameStr = string(token->fStart, token->fContentEnd - token->fStart); Definition* markupChild; if (!markupDef) { fGlobals.emplace_back(MarkType::kEnum, child->fContentStart, child->fContentEnd, @@ -2294,7 +2377,9 @@ bool IncludeParser::parseEnum(Definition* child, Definition* markupDef) { string globalUniqueName = this->uniqueName(fIEnumMap, nameStr); markupChild->fName = globalUniqueName; markupChild->fTerminator = child->fContentEnd; - fIEnumMap[globalUniqueName] = markupChild; + if (!markupChild->fUndocumented) { + fIEnumMap[globalUniqueName] = markupChild; + } } else { markupDef->fTokens.emplace_back(MarkType::kEnum, child->fContentStart, child->fContentEnd, child->fLineCount, markupDef, '\0'); @@ -2302,116 +2387,21 @@ bool IncludeParser::parseEnum(Definition* child, Definition* markupDef) { } SkASSERT(KeyWord::kNone == markupChild->fKeyWord); markupChild->fKeyWord = KeyWord::kEnum; - TextParser enumName(child); - enumName.skipExact("enum "); - enumName.skipWhiteSpace(); - if (enumName.skipExact("class ")) { - enumName.skipWhiteSpace(); + if (isEnumClass) { markupChild->fMarkType = MarkType::kEnumClass; } - const char* nameStart = enumName.fChar; - enumName.skipToSpace(); if (markupDef) { - markupChild->fName = markupDef->fName + "::" + - string(nameStart, (size_t) (enumName.fChar - nameStart)); + markupChild->fName = markupDef->fName + "::" + nameStr; } if (!this->findComments(*child, markupChild)) { return false; } - const char* dataEnd; - do { - parser.skipWhiteSpace(); - if ('}' == parser.peek()) { - break; - } - Definition* comment = nullptr; - // note that comment, if any, can be before or after (on the same line, though) as member - if ('#' == parser.peek()) { - // fixme: handle preprecessor, but just skip it for now - parser.skipToLineStart(); - } - while (parser.startsWith("/*") || parser.startsWith("//")) { - parser.next(); - const char* start = parser.fChar; - const char* end; - if ('*' == parser.peek()) { - end = parser.strnstr("*/", parser.fEnd); - parser.fChar = end; - parser.next(); - parser.next(); - } else { - end = parser.trimmedLineEnd(); - parser.skipToLineStart(); - } - markupChild->fTokens.emplace_back(MarkType::kComment, start, end, parser.fLineCount, - markupChild, '\0'); - comment = &markupChild->fTokens.back(); - comment->fTerminator = end; - if (!this->parseComment(parser.fFileName, start, end, parser.fLineCount, comment)) { - return false; - } - parser.skipWhiteSpace(); - } - parser.skipWhiteSpace(); - const char* memberStart = parser.fChar; - if ('}' == memberStart[0]) { - break; - } - // if there's comment on same the line as member def, output first as if it was before - - parser.skipToNonName(); - string memberName(memberStart, parser.fChar); - if (parser.eof() || !parser.skipWhiteSpace()) { - return parser.reportError("enum member must end with comma 1"); - } - const char* dataStart = parser.fChar; - if ('=' == parser.peek()) { - parser.skipToEndBracket(','); - } - if (!parser.eof() && '#' == parser.peek()) { - // fixme: handle preprecessor, but just skip it for now - continue; - } - if (parser.eof() || ',' != parser.peek()) { - return parser.reportError("enum member must end with comma 2"); - } - dataEnd = parser.fChar; - const char* start = parser.anyOf("/\n"); - SkASSERT(start); - parser.skipTo(start); - if ('/' == parser.next()) { - char slashStar = parser.next(); - if ('/' == slashStar || '*' == slashStar) { - TextParserSave save(&parser); - char doxCheck = parser.next(); - if ((slashStar != doxCheck && '!' != doxCheck) || '<' != parser.next()) { - save.restore(); - } - } - parser.skipWhiteSpace(); - const char* commentStart = parser.fChar; - if ('/' == slashStar) { - parser.skipToEndBracket('\n'); - } else { - parser.skipToEndBracket("*/"); - } - SkASSERT(!parser.eof()); - const char* commentEnd = parser.fChar; - markupChild->fTokens.emplace_back(MarkType::kComment, commentStart, commentEnd, - parser.fLineCount, markupChild, '\0'); - comment = &markupChild->fTokens.back(); - comment->fTerminator = commentEnd; - } - markupChild->fTokens.emplace_back(MarkType::kMember, dataStart, dataEnd, parser.fLineCount, - markupChild, '\0'); - Definition* member = &markupChild->fTokens.back(); - member->fName = memberName; - if (comment) { - member->fChildren.push_back(comment); - comment->fPrivate = true; - } - markupChild->fChildren.push_back(member); - } while (true); + if (markupChild->fUndocumented) { + child->fUndocumented = true; + } + if (!this->parseEnumConst(token, parent->fTokens.end(), markupChild)) { + return false; + } for (auto outsideMember : child->fChildren) { if (Definition::Type::kBracket == outsideMember->fType) { continue; @@ -2435,11 +2425,111 @@ bool IncludeParser::parseEnum(Definition* child, Definition* markupDef) { string fullName = markupChild->fName; markupChild->fName = uniqueName; classDef.fEnums[uniqueName] = markupChild; - fIEnumMap[fullName] = markupChild; + if (!markupChild->fUndocumented) { + fIEnumMap[fullName] = markupChild; + } } return true; } +bool IncludeParser::parseOneEnumConst(list& constList, + Definition* markupChild, bool skipWord) { + auto memberIter = constList.begin(); + const auto memberIterEnd = constList.end(); + if (skipWord) { + SkASSERT(Definition::Type::kWord == memberIter->fType); + memberIter = std::next(memberIter); + SkASSERT(memberIterEnd != memberIter); + } + // token array has parse atoms; child array has comments + bool undocumented = false; + while (memberIterEnd != memberIter) { + while (Bracket::kSlashStar == memberIter->fBracket) { + if (!this->parseComment(memberIter->fFileName, memberIter->fContentStart, + memberIter->fContentEnd, memberIter->fLineCount, markupChild, &undocumented)) { + return false; + } + memberIter = std::next(memberIter); + if (memberIterEnd == memberIter) { + return false; + } + } + if (Bracket::kPound == memberIter->fBracket) { + KeyWord keyWord = memberIter->fKeyWord; + bool sawIf = KeyWord::kIfdef == keyWord || KeyWord::kIf == keyWord + || KeyWord::kElif == keyWord; + if (sawIf || KeyWord::kElse == keyWord) { + if (!parseOneEnumConst(memberIter->fTokens, markupChild, sawIf)) { + return false; + } + } else { + SkASSERT(KeyWord::kEndif == keyWord || KeyWord::kError == keyWord); + } + memberIter = std::next(memberIter); + if (memberIterEnd == memberIter) { + break; + } + continue; + } + while (Definition::Type::kWord != memberIter->fType) { + memberIter = std::next(memberIter); + if (memberIterEnd == memberIter) { + return false; + } + } + auto memberStart = memberIter; + Definition* memberEnd = nullptr; + const char* last; + do { + last = memberIter->fContentEnd; + memberIter = std::next(memberIter); + if (memberIterEnd == memberIter) { + break; + } + memberEnd = &*memberIter; + } while (string::npos == string(last, memberIter->fContentStart).find(',')); + if (!memberEnd) { + return false; + } + if (memberIterEnd != memberIter && Bracket::kSlashSlash == memberIter->fBracket) { + if (!this->parseComment(memberIter->fFileName, memberIter->fContentStart, + memberIter->fContentEnd, memberIter->fLineCount, markupChild, &undocumented)) { + return false; + } + memberIter = std::next(memberIter); + } + markupChild->fTokens.emplace_back(MarkType::kMember, memberStart->fContentStart, + memberEnd->fContentEnd, memberStart->fLineCount, markupChild, '\0'); + Definition* markupMember = &markupChild->fTokens.back(); + string name = string(memberStart->fContentStart, memberStart->length()); + memberStart->fName = name; + markupMember->fName = name; + memberStart->fUndocumented = undocumented; + markupMember->fUndocumented = undocumented; + memberStart->fMarkType = MarkType::kMember; + undocumented = false; + } + return true; +} + +bool IncludeParser::parseEnumConst(list::iterator& tokenIter, + const list::iterator& tokenEnd, Definition* markupChild) { + SkASSERT(Definition::Type::kWord == tokenIter->fType); // should be enum name + tokenIter = std::next(tokenIter); + SkASSERT(tokenEnd != tokenIter); + if (Definition::Type::kKeyWord == tokenIter->fType) { + SkASSERT((unsigned) tokenIter->fKeyWord < SK_ARRAY_COUNT(kKeyWords)); + SkASSERT(KeyProperty::kNumber == kKeyWords[(int) tokenIter->fKeyWord].fProperty); + tokenIter = std::next(tokenIter); + SkASSERT(tokenEnd != tokenIter); + } + SkASSERT(Punctuation::kLeftBrace == tokenIter->fPunctuation); + tokenIter = std::next(tokenIter); + SkASSERT(tokenEnd != tokenIter); + SkASSERT(Bracket::kBrace == tokenIter->fBracket); + return parseOneEnumConst(tokenIter->fTokens, markupChild, false); +} + bool IncludeParser::parseInclude(string name) { fParent = &fIncludeMap[name]; fParent->fName = name; @@ -2473,7 +2563,9 @@ bool IncludeParser::parseMember(Definition* child, Definition* markupDef) { string uniqueName = this->uniqueName(classDef.fMethods, nameStr); markupChild->fName = uniqueName; markupChild->fTerminator = markupChild->fContentEnd; - classDef.fMembers[uniqueName] = markupChild; + if (!markupChild->fUndocumented) { + classDef.fMembers[uniqueName] = markupChild; + } if (child->fParentIndex >= 2) { auto comment = child->fParent->fTokens.begin(); std::advance(comment, child->fParentIndex - 2); @@ -2633,7 +2725,11 @@ bool IncludeParser::parseMethod(Definition* child, Definition* markupDef) { if (!this->findComments(*child, globalMarkupChild)) { return false; } - fIFunctionMap[globalUniqueName] = globalMarkupChild; + if (globalMarkupChild->fUndocumented) { + child->fUndocumented = true; + } else { + fIFunctionMap[globalUniqueName] = globalMarkupChild; + } return true; } markupDef->fTokens.emplace_back(MarkType::kMethod, start, end, tokenIter->fLineCount, @@ -2649,7 +2745,11 @@ bool IncludeParser::parseMethod(Definition* child, Definition* markupDef) { if (!this->findComments(*child, markupChild)) { return false; } - classDef.fMethods[uniqueName] = markupChild; + if (markupChild->fUndocumented) { + tokenIter->fUndocumented = true; + } else { + classDef.fMethods[uniqueName] = markupChild; + } } return true; } @@ -2780,6 +2880,10 @@ bool IncludeParser::parseObject(Definition* child, Definition* markupDef) { // ignored for now break; case KeyWord::kElse: + if (!this->parseObjects(child, markupDef)) { + return false; + } + break; case KeyWord::kElif: // todo: handle these break; @@ -2841,7 +2945,11 @@ bool IncludeParser::parseTypedef(Definition* child, Definition* markupDef) { if (!this->findComments(*child, globalMarkupChild)) { return false; } - fITypedefMap[globalUniqueName] = globalMarkupChild; + if (globalMarkupChild->fUndocumented) { + child->fUndocumented = true; + } else { + fITypedefMap[globalUniqueName] = globalMarkupChild; + } child->fName = nameStr; return true; } diff --git a/tools/bookmaker/includeParser.h b/tools/bookmaker/includeParser.h index cd01687f5d..f132525663 100644 --- a/tools/bookmaker/includeParser.h +++ b/tools/bookmaker/includeParser.h @@ -163,6 +163,7 @@ public: string elidedCodeBlock(const Definition& ); string filteredBlock(string inContents, string filterContents); + bool findCommentAfter(const Definition& includeDef, Definition* markupDef); bool findComments(const Definition& includeDef, Definition* markupDef); Definition* findIncludeObject(const Definition& includeDef, MarkType markType, string typeName); @@ -175,14 +176,17 @@ public: bool isInternalName(const Definition& token); bool isMember(const Definition& token) const; bool isOperator(const Definition& token); + bool isUndocumentable(string filename, const char* start, const char* end, int lineCount); Definition* parentBracket(Definition* parent) const; bool parseChar(); bool parseComment(string filename, const char* start, const char* end, int lineCount, - Definition* markupDef); + Definition* markupDef, bool* undocumentedPtr); bool parseClass(Definition* def, IsStruct); bool parseConst(Definition* child, Definition* markupDef); bool parseDefine(Definition* child, Definition* markupDef); bool parseEnum(Definition* child, Definition* markupDef); + bool parseEnumConst(list::iterator& tokenIter, + const list::iterator& tokenEnd, Definition* markupChild); bool parseFromFile(const char* path) override { this->reset(); @@ -198,6 +202,7 @@ public: bool parseMethod(Definition* child, Definition* markupDef); bool parseObject(Definition* child, Definition* markupDef); bool parseObjects(Definition* parent, Definition* markupDef); + bool parseOneEnumConst(list& constList, Definition* markupChild, bool skipWord); bool parseTemplate(Definition* child, Definition* markupDef); bool parseTypedef(Definition* child, Definition* markupDef); bool parseUsing(); @@ -215,6 +220,9 @@ public: } void pushBracket(Bracket bracket) { + if ("#else" == string(fChar, 5)) { + SkDebugf(""); + } this->setBracketShortCuts(bracket); fParent->fTokens.emplace_back(bracket, fChar, fLineCount, fParent, '\0'); Definition* container = &fParent->fTokens.back(); diff --git a/tools/bookmaker/includeWriter.cpp b/tools/bookmaker/includeWriter.cpp index 77851f6c45..379c4eba06 100644 --- a/tools/bookmaker/includeWriter.cpp +++ b/tools/bookmaker/includeWriter.cpp @@ -20,15 +20,6 @@ bool IncludeWriter::checkChildCommentLength(const Definition* parent, MarkType c oneMember = true; int lineLen = 0; for (auto& itemChild : item->fChildren) { - if (MarkType::kExperimental == itemChild->fMarkType) { - lineLen = sizeof("experimental") - 1; - break; - } - if (MarkType::kDeprecated == itemChild->fMarkType) { - lineLen = sizeof("deprecated") - 1; - // todo: look for 'soon' - break; - } if (MarkType::kLine == itemChild->fMarkType) { lineLen = itemChild->length(); break; @@ -100,15 +91,6 @@ bool IncludeWriter::descriptionOut(const Definition* def, SkipFirstLine skipFirs int commentLen = (int) (def->fContentEnd - commentStart); bool breakOut = false; SkDEBUGCODE(bool wroteCode = false); - if (def->fDeprecated) { - if (fReturnOnWrite) { - return true; - } - string message = def->incompleteMessage(Definition::DetailsType::kSentence); - this->writeString(message); - this->lfcr(); - wroteSomething = true; - } const Definition* lastDescription = def; for (auto prop : def->fChildren) { fLastDescription = lastDescription; @@ -169,61 +151,6 @@ bool IncludeWriter::descriptionOut(const Definition* def, SkipFirstLine skipFirs this->lfcr(); wroteSomething = true; } - case MarkType::kDeprecated: - case MarkType::kPrivate: - commentLen = (int) (prop->fStart - commentStart); - if (commentLen > 0) { - SkASSERT(commentLen < 1000); - if (Wrote::kNone != this->rewriteBlock(commentLen, commentStart, Phrase::kNo)) { - if (fReturnOnWrite) { - return true; - } - this->lfcr(); - wroteSomething = true; - } - } - commentStart = prop->fContentStart; - if (MarkType::kPrivate != prop->fMarkType && ' ' < commentStart[0]) { - commentStart = strchr(commentStart, '\n'); - } - if (MarkType::kBug == prop->fMarkType) { - commentStart = prop->fContentEnd; - } - commentLen = (int) (prop->fContentEnd - commentStart); - if (commentLen > 0) { - wroteSomething |= this->writeBlockIndent(commentLen, commentStart, false); - if (wroteSomething && fReturnOnWrite) { - return true; - } - const char* end = commentStart + commentLen; - while (end > commentStart && ' ' == end[-1]) { - --end; - } - if (end > commentStart && '\n' == end[-1]) { - this->lfcr(); - } - } - commentStart = prop->fTerminator; - commentLen = (int) (def->fContentEnd - commentStart); - break; - case MarkType::kExperimental: - commentStart = prop->fContentStart; - if (' ' < commentStart[0]) { - commentStart = strchr(commentStart, '\n'); - } - commentLen = (int) (prop->fContentEnd - commentStart); - if (commentLen > 0) { - if (Wrote::kNone != this->rewriteBlock(commentLen, commentStart, Phrase::kNo)) { - if (fReturnOnWrite) { - return true; - } - this->lfcr(); - wroteSomething = true; - } - } - commentStart = prop->fTerminator; - commentLen = (int) (def->fContentEnd - commentStart); - break; case MarkType::kFormula: { commentLen = prop->fStart - commentStart; if (commentLen > 0) { @@ -382,7 +309,7 @@ bool IncludeWriter::descriptionOut(const Definition* def, SkipFirstLine skipFirs if (!breakOut) { commentLen = (int) (def->fContentEnd - commentStart); } - SkASSERT(wroteCode || (commentLen > 0 && commentLen < 1500) || def->fDeprecated); + SkASSERT(wroteCode || (commentLen > 0 && commentLen < 1500)); if (commentLen > 0) { if (Wrote::kNone != this->rewriteBlock(commentLen, commentStart, phrase)) { if (fReturnOnWrite) { @@ -543,9 +470,7 @@ void IncludeWriter::enumHeaderOut(RootDefinition* root, const Definition& child) const Definition* IncludeWriter::enumMemberForComment(const Definition* currentEnumItem) const { for (auto constItem : currentEnumItem->fChildren) { - if (MarkType::kLine == constItem->fMarkType - || MarkType::kExperimental == constItem->fMarkType - || MarkType::kDeprecated == constItem->fMarkType) { + if (MarkType::kLine == constItem->fMarkType) { return constItem; } } @@ -562,9 +487,6 @@ string IncludeWriter::enumMemberComment(const Definition* currentEnumItem, shortComment = string(constItem->fContentStart, constItem->length()); break; } - if (IncompleteAllowed(constItem->fMarkType)) { - shortComment = constItem->fParent->incompleteMessage(Definition::DetailsType::kPhrase); - } } if (!shortComment.length()) { currentEnumItem->reportError("missing #Line or #Deprecated or #Experimental"); @@ -675,7 +597,7 @@ void IncludeWriter::enumMemberOut(const Definition* currentEnumItem, const Defin // put ones that fit on same line, ones that are too big wrap void IncludeWriter::enumMembersOut(Definition& child) { ItemState state = ItemState::kNone; - const Definition* currentEnumItem; + const Definition* currentEnumItem = nullptr; LastItem last = { nullptr, nullptr }; auto brace = child.fChildren[0]; if (KeyWord::kClass == brace->fKeyWord) { @@ -704,14 +626,14 @@ void IncludeWriter::enumMembersOut(Definition& child) { continue; } } - if (ItemState::kNone != state) { + if (ItemState::kNone != state && currentEnumItem) { this->enumMemberOut(currentEnumItem, child, item, preprocessor); item.reset(); this->setStartBack(token.fContentStart, &token); state = ItemState::kNone; last.fStart = nullptr; } - SkASSERT(ItemState::kNone == state); + SkASSERT(ItemState::kNone == state || !currentEnumItem); if (!last.fStart) { last.fStart = fStart; } @@ -721,7 +643,7 @@ void IncludeWriter::enumMembersOut(Definition& child) { if (ItemState::kName == state) { state = this->enumMemberName(child, nullptr, &item, &last, ¤tEnumItem); } - if (ItemState::kValue == state || ItemState::kComment == state) { + if ((ItemState::kValue == state || ItemState::kComment == state) && currentEnumItem) { this->enumMemberOut(currentEnumItem, child, item, preprocessor); } this->indentOut(); @@ -800,6 +722,7 @@ void IncludeWriter::enumSizeItems(const Definition& child) { IterState* iterState = &iterStack[0]; Preprocessor preprocessor; string enumName; + bool undocumented = false; while (iterState->fDefIter != iterState->fDefEnd) { auto& token = *iterState->fDefIter++; if (this->enumPreprocessor(&token, MemberPass::kCount, iterStack, &iterState, @@ -826,7 +749,9 @@ void IncludeWriter::enumSizeItems(const Definition& child) { } } if (ItemState::kNone != state) { - this->checkEnumLengths(child, enumName, &lengths); + if (!undocumented) { + this->checkEnumLengths(child, enumName, &lengths); + } lengths.fCurValue = 0; state = ItemState::kNone; } @@ -834,9 +759,10 @@ void IncludeWriter::enumSizeItems(const Definition& child) { lastEnd = token.fContentEnd; lengths.fCurName = (int) (lastEnd - token.fContentStart); enumName = string(token.fContentStart, lengths.fCurName); + undocumented = token.fUndocumented; state = ItemState::kName; } - if (ItemState::kNone != state) { + if (ItemState::kNone != state && !undocumented) { this->checkEnumLengths(child, enumName, &lengths); } fEnumItemValueTab = lengths.fLongestName + fIndent + 1 /* 1: , */ ; @@ -872,8 +798,7 @@ const Definition* IncludeWriter::matchMemberName(string matchName, const Definit enumItem = testItem; break; } - SkASSERT(enumItem); - return enumItem; + return enumItem; // returns nullptr if matchName is undocumented } // walk children and output complete method doxygen description @@ -891,9 +816,6 @@ void IncludeWriter::methodOut(Definition* method, const Definition& child) { this->indentIn(IndentKind::kMethodOut); fIndentNext = false; } - if (string::npos != method->fName.find("validate")) { - SkDebugf(""); - } if (method->fChildren.end() != std::find_if(method->fChildren.begin(), method->fChildren.end(), [](const Definition* def) { return MarkType::kPopulate == def->fMarkType; } )) { std::list::iterator iter; @@ -982,11 +904,7 @@ void IncludeWriter::structOut(const Definition* root, const Definition& child, this->writeString(child.fName.c_str()); fIndent += 4; this->lfcr(); - if (child.fDeprecated) { - this->writeString(child.incompleteMessage(Definition::DetailsType::kSentence)); - } else { - this->rewriteBlock((int)(commentEnd - commentStart), commentStart, Phrase::kNo); - } + this->rewriteBlock((int)(commentEnd - commentStart), commentStart, Phrase::kNo); fIndent -= 4; this->lfcr(); this->writeCommentTrailer(OneLine::kNo); @@ -1519,10 +1437,6 @@ bool IncludeWriter::populate(Definition* def, ParentPair* prevPair, RootDefiniti } method = this->findMethod(methodName, root); if (!method) { - if (fBmhStructDef && fBmhStructDef->fDeprecated) { - fContinuation = nullptr; - continue; - } return child.reportError("method not found"); } this->methodOut(method, child); @@ -1546,9 +1460,6 @@ bool IncludeWriter::populate(Definition* def, ParentPair* prevPair, RootDefiniti this->methodOut(method, child); sawConst = false; continue; - } else if (fBmhStructDef && fBmhStructDef->fDeprecated) { - fContinuation = nullptr; - continue; } if (KeyWord::kTemplate == child.fParent->fKeyWord) { // incomplete; no support to template specialization in public includes @@ -1567,6 +1478,9 @@ bool IncludeWriter::populate(Definition* def, ParentPair* prevPair, RootDefiniti if (this->isInternalName(child)) { continue; } + if (child.fUndocumented) { + continue; + } if (KeyWord::kTemplate == child.fParent->fKeyWord) { // todo: support template specializations continue; @@ -1619,6 +1533,9 @@ bool IncludeWriter::populate(Definition* def, ParentPair* prevPair, RootDefiniti continue; } if (Definition::Type::kKeyWord == child.fType) { + if (child.fUndocumented) { + continue; + } switch (child.fKeyWord) { case KeyWord::kStruct: case KeyWord::kClass: @@ -1745,34 +1662,32 @@ bool IncludeWriter::populate(Definition* def, ParentPair* prevPair, RootDefiniti priorBlock = test; } // FIXME: trigger error earlier if inner #Struct or #Class is missing #Code - if (!fBmhStructDef->fDeprecated) { - SkASSERT(codeBlock); - SkASSERT(nextBlock); // FIXME: check enum for correct order earlier - const char* commentStart = codeBlock->fTerminator; - const char* commentEnd = nextBlock->fStart; - // FIXME: trigger error if #Code is present but comment is before it earlier - SkASSERT(priorBlock); // code always preceded by #Line (I think) - TextParser priorComment(priorBlock->fFileName, - priorBlock->fTerminator, codeBlock->fStart, - priorBlock->fLineCount); - priorComment.trimEnd(); - if (!priorComment.eof()) { - return priorBlock->reportError( - "expect no comment before #Code"); - } - TextParser nextComment(codeBlock->fFileName, commentStart, - commentEnd, codeBlock->fLineCount); - nextComment.trimEnd(); - if (!priorComment.eof()) { - return priorBlock->reportError( - "expect comment after #Code"); - } - if (!nextComment.eof()) { - - } - fIndentNext = true; - this->structOut(root, *fBmhStructDef, commentStart, commentEnd); + SkASSERT(codeBlock); + SkASSERT(nextBlock); // FIXME: check enum for correct order earlier + const char* commentStart = codeBlock->fTerminator; + const char* commentEnd = nextBlock->fStart; + // FIXME: trigger error if #Code is present but comment is before it earlier + SkASSERT(priorBlock); // code always preceded by #Line (I think) + TextParser priorComment(priorBlock->fFileName, + priorBlock->fTerminator, codeBlock->fStart, + priorBlock->fLineCount); + priorComment.trimEnd(); + if (!priorComment.eof()) { + return priorBlock->reportError( + "expect no comment before #Code"); } + TextParser nextComment(codeBlock->fFileName, commentStart, + commentEnd, codeBlock->fLineCount); + nextComment.trimEnd(); + if (!priorComment.eof()) { + return priorBlock->reportError( + "expect comment after #Code"); + } + if (!nextComment.eof()) { + + } + fIndentNext = true; + this->structOut(root, *fBmhStructDef, commentStart, commentEnd); } fDeferComment = nullptr; } else { @@ -1957,14 +1872,11 @@ bool IncludeWriter::populate(Definition* def, ParentPair* prevPair, RootDefiniti fIndentNext = true; } SkASSERT(fBmhStructDef); - if (!fBmhStructDef->fDeprecated) { - memberEnd = this->structMemberOut(memberStart, child); - startDef = &child; - this->setStart(child.fContentEnd + 1, &child); - fDeferComment = nullptr; - } - } else if (MarkType::kNone == child.fMarkType && sawConst - && fEnumDef && !fEnumDef->fDeprecated) { + memberEnd = this->structMemberOut(memberStart, child); + startDef = &child; + this->setStart(child.fContentEnd + 1, &child); + fDeferComment = nullptr; + } else if (MarkType::kNone == child.fMarkType && sawConst && fEnumDef) { const Definition* bmhConst = nullptr; string match; if (root) { diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp index 90702d8f63..20a48ae1bb 100644 --- a/tools/bookmaker/mdOut.cpp +++ b/tools/bookmaker/mdOut.cpp @@ -75,14 +75,8 @@ string MdOut::anchorDef(string str, string name) { if (!std::any_of(allDefs.begin(), allDefs.end(), [str](AnchorDef compare) { return compare.fDef == str; } )) { MarkType markType = fLastDef->fMarkType; - if (MarkType::kMethod == markType - && std::any_of(fLastDef->fChildren.begin(), fLastDef->fChildren.end(), - [](const Definition* compare) { - return IncompleteAllowed(compare->fMarkType); } )) { - markType = MarkType::kDeprecated; - } if (MarkType::kMethod == markType && fLastDef->fClone) { - markType = MarkType::kDeprecated; // TODO: hack to allow missing reference + SkASSERT(0); // incomplete } allDefs.push_back( { str, markType } ); } @@ -581,7 +575,7 @@ void MdOut::DefinedState::setLink() { && fGlobals->fRefMap.end() != fGlobals->fRefMap.find(fWord + ' '); if (!withSpace && (Resolvable::kInclude == fResolvable ? !fInMatrix : '"' != fPriorSeparator.back() || '"' != fSeparator.back())) { - SkDebugf("fWord %s not found\n", fWord.c_str()); + SkDebugf("word %s not found\n", fWord.c_str()); fBmhParser->fGlobalNames.fRefMap[fWord] = nullptr; } } @@ -601,6 +595,12 @@ string MdOut::addReferences(const char* refStart, const char* refEnd, Resolvable break; } s.fWord = string(start, s.fEnd - start); + if ("TODO" == s.fWord) { + while('\n' != *s.fEnd++) + ; + start = s.fEnd; + continue; + } s.setLower(); if (s.setPriorSpaceWord(&start)) { continue; @@ -767,8 +767,7 @@ void MdOut::checkAnchors() { break; } if (allRefsEnded || (!allDefsEnded && allDefsIter->fDef < *allRefsIter)) { - if (MarkType::kParam != allDefsIter->fMarkType - && !IncompleteAllowed(allDefsIter->fMarkType)) { + if (MarkType::kParam != allDefsIter->fMarkType) { // If undocumented but parent or child is referred to: good enough for now bool goodEnough = false; if ("undocumented" == defIter->first) { @@ -845,9 +844,6 @@ bool MdOut::checkParamReturnBody(const Definition* def) { } void MdOut::childrenOut(Definition* def, const char* start) { - if (MarkType::kDeprecated == def->fMarkType || MarkType::kExperimental == def->fMarkType) { - return; - } const char* end; fLineCount = def->fLineCount; if (MarkType::kEnumClass == def->fMarkType) { @@ -1376,11 +1372,6 @@ void MdOut::markTypeOut(Definition* def, const Definition** prior) { FPRINTF("%s", out_table_data_description_start().c_str()); // start of Description this->lfAlways(1); } break; - case MarkType::kDeprecated: - this->writeString(def->fParent->incompleteMessage( - Definition::DetailsType::kSentence).c_str()); - this->lf(2); - break; case MarkType::kDescription: fInDescription = true; this->writePending(); @@ -1436,11 +1427,6 @@ void MdOut::markTypeOut(Definition* def, const Definition** prior) { fLiteralAndIndent = true; } } break; - case MarkType::kExperimental: - this->writeString(def->fParent->incompleteMessage( - Definition::DetailsType::kSentence).c_str()); - this->lf(2); - break; case MarkType::kExternal: break; case MarkType::kFile: @@ -1522,17 +1508,12 @@ void MdOut::markTypeOut(Definition* def, const Definition** prior) { this->lf(2); fTableState = TableState::kNone; fMethod = def; - if ("SkTextBlobBuilder::allocRun_2" == def->fName) { - SkDebugf(""); - } Definition* iMethod = fIncludeParser.findMethod(*def); if (iMethod) { fMethod = iMethod; paramMap.fParent = &fBmhParser.fGlobalNames; paramMap.setParams(def, iMethod); fNames = ¶mMap; - } else { - SkDebugf(""); } } break; case MarkType::kNoExample: @@ -1721,12 +1702,6 @@ void MdOut::markTypeOut(Definition* def, const Definition** prior) { } } } break; - case MarkType::kPrivate: - this->writeString("Private:"); - this->writeSpace(); - this->writeBlock(def->length(), def->fContentStart); - this->lf(2); - break; case MarkType::kReturn: this->returnHeaderOut(prior, def); break; @@ -1972,8 +1947,6 @@ void MdOut::markTypeOut(Definition* def, const Definition** prior) { break; case MarkType::kPhraseDef: break; - case MarkType::kPrivate: - break; case MarkType::kSubtopic: SkASSERT(def); do { @@ -2375,9 +2348,6 @@ void MdOut::subtopicOut(string key, const vector& data, const Defin items[entryName] = entry; } for (auto entry : items) { - if (entry.second->fDeprecated) { - continue; - } if (!this->subtopicRowOut(entry.first, entry.second)) { return; } diff --git a/tools/bookmaker/parserCommon.h b/tools/bookmaker/parserCommon.h index f31cbd63cd..f8e0ca86c0 100644 --- a/tools/bookmaker/parserCommon.h +++ b/tools/bookmaker/parserCommon.h @@ -64,6 +64,9 @@ public: } void addDefinition(Definition* def) { + if (KeyWord::kElse == def->fKeyWord) { + SkDebugf(""); + } fParent->fChildren.push_back(def); fParent = def; } @@ -161,6 +164,9 @@ public: } void setAsParent(Definition* definition) { + if (KeyWord::kElse == definition->fKeyWord) { + SkDebugf(""); + } if (fParent) { fParent->fChildren.push_back(definition); definition->fParent = fParent; diff --git a/tools/bookmaker/selfCheck.cpp b/tools/bookmaker/selfCheck.cpp index 1c822c2d05..341b9e38e8 100644 --- a/tools/bookmaker/selfCheck.cpp +++ b/tools/bookmaker/selfCheck.cpp @@ -79,8 +79,8 @@ protected: // only check methods for now return; } - bool containsMarkTypeIn = csChild->fDeprecated // no markup for deprecated - || Definition::MethodType::kConstructor == csChild->fMethodType + bool containsMarkTypeIn = + Definition::MethodType::kConstructor == csChild->fMethodType || Definition::MethodType::kDestructor == csChild->fMethodType || Definition::MethodType::kOperator == csChild->fMethodType || csChild->fClone; diff --git a/tools/bookmaker/spellCheck.cpp b/tools/bookmaker/spellCheck.cpp index c6cfe5d079..c8de4a3953 100644 --- a/tools/bookmaker/spellCheck.cpp +++ b/tools/bookmaker/spellCheck.cpp @@ -180,8 +180,6 @@ bool SpellCheck::check(Definition* def) { } break; case MarkType::kDefine: break; - case MarkType::kDeprecated: - break; case MarkType::kDescription: fInDescription = true; break; @@ -195,8 +193,6 @@ bool SpellCheck::check(Definition* def) { break; case MarkType::kExample: break; - case MarkType::kExperimental: - break; case MarkType::kExternal: break; case MarkType::kFile: @@ -270,8 +266,6 @@ bool SpellCheck::check(Definition* def) { break; case MarkType::kPopulate: break; - case MarkType::kPrivate: - break; case MarkType::kReturn: break; case MarkType::kRow: diff --git a/tools/bookmaker/textParser.h b/tools/bookmaker/textParser.h index ffe5e785f7..9ecd4665cd 100644 --- a/tools/bookmaker/textParser.h +++ b/tools/bookmaker/textParser.h @@ -58,6 +58,46 @@ public: return nullptr; } + // words must be alpha only + string anyWord(const vector& wordList, int spaces) const { + const char* matchStart = fChar; + do { + int count = spaces; + while (matchStart < fEnd && !isalpha(matchStart[0])) { + ++matchStart; + } + const char* matchEnd = matchStart; + const char* nextWord = nullptr; + while (matchEnd < fEnd) { + if (isalpha(matchEnd[0])) { + ; + } else if (' ' == matchEnd[0] && --count >= 0) { + if (!nextWord) { + nextWord = matchEnd; + } + } else { + break; + } + ++matchEnd; + } + size_t matchLen = matchEnd - matchStart; + for (auto word : wordList) { + if (word.length() != matchLen) { + continue; + } + for (unsigned index = 0; index < matchLen; ++index) { + if (tolower(matchStart[index]) != word[index]) { + goto nextWord; + } + } + return word; + nextWord: ; + } + matchStart = nextWord ? nextWord : matchEnd; + } while (matchStart < fEnd); + return ""; + } + bool back(const char* pattern) { size_t len = strlen(pattern); const char* start = fChar - len;