From a19a84449870b1757753ce9e130b7ed4831388e5 Mon Sep 17 00:00:00 2001 From: David Capello Date: Wed, 13 Nov 2024 10:04:58 -0300 Subject: [PATCH] Update comment about DocApi class --- src/app/doc_api.h | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/src/app/doc_api.h b/src/app/doc_api.h index a3c59fa4b..dcb1eb910 100644 --- a/src/app/doc_api.h +++ b/src/app/doc_api.h @@ -1,5 +1,5 @@ // Aseprite -// Copyright (C) 2019 Igara Studio S.A. +// Copyright (C) 2019-2024 Igara Studio S.A. // Copyright (C) 2001-2018 David Capello // // This program is distributed under the terms of @@ -37,10 +37,26 @@ namespace app { using namespace doc; - // Old high-level API. The new way is to create Cmds and add them - // directly to the transaction. + // High-level API to modify a document adding undo information, i.e. + // adding new "Cmd"s in the given transaction. + // + // In the past there were plans to remove this class, but it got + // bigger and bigger and there wasn't a real replacement. Some + // attempts to avoid adding new member functions in DocApi are: + // + // 1. Creating new standalone functions like the ones from + // doc_range_ops.h, or util/cel_ops.h + // 2. Creating a new Command/QuickCommand, although that only makes + // sense if we want to expose the functionality to the end-user, + // and the number of parameters is quite small. + // + // Sometimes complex sprite changes require storing some special + // state until the transaction ends, like HandleLinkedCels and the + // m_linkedCels to map linked cels in the source sprite/layer and + // replicate them in the destination sprite/layer. This requires + // such coordination with moveCel()/copyCel() methods that it would + // be quite hard to replicate that in a standalone function. // - // TODO refactor this class in several Cmd, don't make it bigger class DocApi { public: DocApi(Doc* document, Transaction& transaction);