Bug 1463327 - part 4: Add comments to explain which kind of methods should be public methods r?m_kato draft
authorMasayuki Nakano <masayuki@d-toybox.com>
Tue, 22 May 2018 20:15:05 +0900
changeset 799311 7bac98f1978f499f6be6e1bf8f8ebbbe12c8941c
parent 799310 9c29466fcf3168465c53eac2ea89e45a3af6ad87
push id111000
push usermasayuki@d-toybox.com
push dateThu, 24 May 2018 12:43:37 +0000
reviewersm_kato
bugs1463327
milestone62.0a1
Bug 1463327 - part 4: Add comments to explain which kind of methods should be public methods r?m_kato MozReview-Commit-ID: 6l8ZiMWEYCI
editor/libeditor/EditorBase.h
editor/libeditor/HTMLEditor.h
editor/libeditor/TextEditor.h
--- a/editor/libeditor/EditorBase.h
+++ b/editor/libeditor/EditorBase.h
@@ -193,16 +193,26 @@ enum class SplitAtEdges
  * delegate the actual commands to the editor independent of the XPFE
  * implementation.
  */
 class EditorBase : public nsIEditor
                  , public nsISelectionListener
                  , public nsSupportsWeakReference
 {
 public:
+  /****************************************************************************
+   * NOTE: DO NOT MAKE YOUR NEW METHODS PUBLIC IF they are called by other
+   *       classes under libeditor except EditorEventListener and
+   *       HTMLEditorEventListener because each public method which may fire
+   *       eEditorInput event will need to instantiate new stack class for
+   *       managing input type value of eEditorInput and cache some objects
+   *       for smarter handling.  In other words, when you add new root
+   *       method to edit the DOM tree, you can make your new method public.
+   ****************************************************************************/
+
   typedef dom::Element Element;
   typedef dom::Selection Selection;
   typedef dom::Text Text;
 
   NS_DECL_CYCLE_COLLECTING_ISUPPORTS
   NS_DECL_CYCLE_COLLECTION_CLASS_AMBIGUOUS(EditorBase, nsIEditor)
 
   // nsIEditor methods
@@ -655,16 +665,25 @@ public:
 
   /** Resyncs spellchecking state (enabled/disabled).  This should be called
     * when anything that affects spellchecking state changes, such as the
     * spellcheck attribute value.
     */
   void SyncRealTimeSpell();
 
 protected: // May be called by friends.
+  /****************************************************************************
+   * Some classes like TextEditRules, HTMLEditRules, WSRunObject which are
+   * part of handling edit actions are allowed to call the following protected
+   * methods.  However, those methods won't prepare caches of some objects
+   * which are necessary for them.  So, if you want some following methods
+   * to do that for you, you need to create a wrapper method in public scope
+   * and call it.
+   ****************************************************************************/
+
   /**
    * InsertTextWithTransaction() inserts aStringToInsert to aPointToInsert or
    * better insertion point around it.  If aPointToInsert isn't in a text node,
    * this method looks for the nearest point in a text node with
    * FindBetterInsertionPoint().  If there is no text node, this creates
    * new text node and put aStringToInsert to it.
    *
    * @param aDocument       The document of this editor.
--- a/editor/libeditor/HTMLEditor.h
+++ b/editor/libeditor/HTMLEditor.h
@@ -69,16 +69,26 @@ class HTMLEditor final : public TextEdit
                        , public nsIHTMLAbsPosEditor
                        , public nsITableEditor
                        , public nsIHTMLInlineTableEditor
                        , public nsIEditorStyleSheets
                        , public nsICSSLoaderObserver
                        , public nsStubMutationObserver
 {
 public:
+  /****************************************************************************
+   * NOTE: DO NOT MAKE YOUR NEW METHODS PUBLIC IF they are called by other
+   *       classes under libeditor except EditorEventListener and
+   *       HTMLEditorEventListener because each public method which may fire
+   *       eEditorInput event will need to instantiate new stack class for
+   *       managing input type value of eEditorInput and cache some objects
+   *       for smarter handling.  In other words, when you add new root
+   *       method to edit the DOM tree, you can make your new method public.
+   ****************************************************************************/
+
   NS_DECL_ISUPPORTS_INHERITED
   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(HTMLEditor, TextEditor)
 
   // nsStubMutationObserver overrides
   NS_DECL_NSIMUTATIONOBSERVER_CONTENTAPPENDED
   NS_DECL_NSIMUTATIONOBSERVER_CONTENTINSERTED
   NS_DECL_NSIMUTATIONOBSERVER_CONTENTREMOVED
 
@@ -273,16 +283,25 @@ public:
    * @param aUIAnonymousElement [IN] the inline table editing UI element
    */
   nsresult DoInlineTableEditingAction(const Element& aUIAnonymousElement);
 
   already_AddRefed<Element>
   GetElementOrParentByTagName(const nsAString& aTagName, nsINode* aNode);
 
 protected: // May be called by friends.
+  /****************************************************************************
+   * Some classes like TextEditRules, HTMLEditRules, WSRunObject which are
+   * part of handling edit actions are allowed to call the following protected
+   * methods.  However, those methods won't prepare caches of some objects
+   * which are necessary for them.  So, if you want some following methods
+   * to do that for you, you need to create a wrapper method in public scope
+   * and call it.
+   ****************************************************************************/
+
   /**
    * DeleteSelectionWithTransaction() removes selected content or content
    * around caret with transactions.
    *
    * @param aDirection          How much range should be removed.
    * @param aStripWrappers      Whether the parent blocks should be removed
    *                            when they become empty.
    */
--- a/editor/libeditor/TextEditor.h
+++ b/editor/libeditor/TextEditor.h
@@ -34,16 +34,26 @@ class Selection;
  * The text editor implementation.
  * Use to edit text document represented as a DOM tree.
  */
 class TextEditor : public EditorBase
                  , public nsIPlaintextEditor
                  , public nsIEditorMailSupport
 {
 public:
+  /****************************************************************************
+   * NOTE: DO NOT MAKE YOUR NEW METHODS PUBLIC IF they are called by other
+   *       classes under libeditor except EditorEventListener and
+   *       HTMLEditorEventListener because each public method which may fire
+   *       eEditorInput event will need to instantiate new stack class for
+   *       managing input type value of eEditorInput and cache some objects
+   *       for smarter handling.  In other words, when you add new root
+   *       method to edit the DOM tree, you can make your new method public.
+   ****************************************************************************/
+
   NS_DECL_ISUPPORTS_INHERITED
   NS_DECL_CYCLE_COLLECTION_CLASS_INHERITED(TextEditor, EditorBase)
 
   TextEditor();
 
   // nsIPlaintextEditor methods
   NS_DECL_NSIPLAINTEXTEDITOR
 
@@ -158,16 +168,25 @@ public:
   /**
    * OnCompositionEnd() is called when editor receives an eCompositionChange
    * event and it's followed by eCompositionEnd event and after
    * OnCompositionChange() is called.
    */
   void OnCompositionEnd(WidgetCompositionEvent& aCompositionEndEvent);
 
 protected: // May be called by friends.
+  /****************************************************************************
+   * Some classes like TextEditRules, HTMLEditRules, WSRunObject which are
+   * part of handling edit actions are allowed to call the following protected
+   * methods.  However, those methods won't prepare caches of some objects
+   * which are necessary for them.  So, if you want some following methods
+   * to do that for you, you need to create a wrapper method in public scope
+   * and call it.
+   ****************************************************************************/
+
   // Overrides of EditorBase
   virtual nsresult RemoveAttributeOrEquivalent(
                      Element* aElement,
                      nsAtom* aAttribute,
                      bool aSuppressTransaction) override;
   virtual nsresult SetAttributeOrEquivalent(Element* aElement,
                                             nsAtom* aAttribute,
                                             const nsAString& aValue,