src/jdk.vm.ci/share/classes/jdk.vm.ci.code/src/jdk/vm/ci/code/site/Mark.java

@@ -1,7 +1,7 @@
 /*
- * Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2016, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.

@@ -23,26 +23,36 @@
 package jdk.vm.ci.code.site;
 
 import java.util.Objects;
 
 /**
- * Represents a mark in the machine code that can be used by the runtime for its own purposes. A
- * mark can reference other marks.
+ * Associates arbitrary information with a position in machine code. For example, HotSpot specific
+ * code in a compiler backend may use this to denote the position of a safepoint, exception handler
+ * entry point, verified entry point etc.
  */
 public final class Mark extends Site {
 
+    /**
+     * An object denoting extra semantic information about the machine code position of this mark.
+     */
     public final Object id;
 
+    /**
+     * Creates a mark that associates {@code id} with the machine code position {@code pcOffset}.
+     *
+     * @param pcOffset
+     * @param id
+     */
     public Mark(int pcOffset, Object id) {
         super(pcOffset);
         this.id = id;
     }
 
     @Override
     public String toString() {
         if (id == null) {
-            return String.format("%d[<mar>]", pcOffset);
+            return String.format("%d[<mark>]", pcOffset);
         } else if (id instanceof Integer) {
             return String.format("%d[<mark with id %s>]", pcOffset, Integer.toHexString((Integer) id));
         } else {
             return String.format("%d[<mark with id %s>]", pcOffset, id.toString());
         }