Bug 1463327 - part 4: Add comments to explain which kind of methods should be public methods r=m_kato
authorMasayuki Nakano <masayuki@d-toybox.com>
Tue, 22 May 2018 20:15:05 +0900
changeset 419737 ac00527001f9690be6d4f66feb4f8cf50577b02c
parent 419736 5d7484ed3b99d57a9cbf540d9204974eb481aced
child 419738 fdf92ddfbf862b8a2c801e06c032c01a906f7898
push id103609
push usercbrindusan@mozilla.com
push dateFri, 25 May 2018 00:09:58 +0000
treeherdermozilla-inbound@7fe1e764c547 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersm_kato
bugs1463327
milestone62.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
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,