diff --git a/core/src/main/resources/hudson/lifecycle/WindowsInstallerLink/_restart.jelly b/core/src/main/resources/hudson/lifecycle/WindowsInstallerLink/_restart.jelly
index f05f1098e81e5f11af15d2f96729fb8029849cfa..320325c35b986609878ebfdfc1900448005d5567 100644
--- a/core/src/main/resources/hudson/lifecycle/WindowsInstallerLink/_restart.jelly
+++ b/core/src/main/resources/hudson/lifecycle/WindowsInstallerLink/_restart.jelly
@@ -6,7 +6,7 @@
       <h1 style="margin-top:4em">
         ${%Please wait while Hudson is restarting}<span id="progress">...</span>
       </h1>
-      <p style="color:grey">
+      <p style="color:gray;">
         ${%blurb}
       </p>
       
diff --git a/core/src/main/resources/lib/form/submit.jelly b/core/src/main/resources/lib/form/submit.jelly
index dbc37b0f9e7a0803a024c2d6cfa55040079d8379..72000de18e5185dddbec3262af74153a46a9c175 100644
--- a/core/src/main/resources/lib/form/submit.jelly
+++ b/core/src/main/resources/lib/form/submit.jelly
@@ -1,6 +1,11 @@
-<!--
-  Submit button
--->
 <j:jelly xmlns:j="jelly:core" xmlns:s="jelly:stapler" xmlns:d="jelly:define">
+  <s:documentation>
+    Submit button themed by YUI. This should be always
+    used instead of the plain &lt;input tag.
+
+    <s:attribute name="value" use="required">
+      The text of the submit button. Something like "submit", "OK", etc.
+    </s:attribute>
+  </s:documentation>
   <input type="submit" name="Submit" value="${attrs.value}" class="submit-button" />
 </j:jelly>
diff --git a/core/src/main/resources/lib/layout/header.jelly b/core/src/main/resources/lib/layout/header.jelly
index 90f27a9dca53d3e807e6f03312018b6193c4e7b3..8da2dbb8f1fcfa9e1b3658947c4bb831ffe2713b 100644
--- a/core/src/main/resources/lib/layout/header.jelly
+++ b/core/src/main/resources/lib/layout/header.jelly
@@ -1,4 +1,9 @@
 <j:jelly xmlns:j="jelly:core" xmlns:s="jelly:stapler" xmlns:d="jelly:define">
+  <s:documentation>
+    Header portion of the HTML page, that gets rendered into the &lt;head> tag.
+    Multiple &lt;l:header> elements can be specified, and can even come after
+    &lt;l:main-panel>.
+  </s:documentation>
   <j:if test="${mode=='header'}">
     <d:invokeBody />
   </j:if>
diff --git a/core/src/main/resources/lib/layout/layout.jelly b/core/src/main/resources/lib/layout/layout.jelly
index 49e8ff20870507507cd7f550043cbb2658a2fa4d..7b80b6a045db8bd49f1f6d75a4e562e5335d3a1a 100644
--- a/core/src/main/resources/lib/layout/layout.jelly
+++ b/core/src/main/resources/lib/layout/layout.jelly
@@ -1,19 +1,32 @@
-<!--
-  Outermost page layout. This is used with nested <side-panel> and <main-panel>
-  to form Hudson's basic HTML layout.
-
-  Attributes:
-   title : controls the HTML page title. Mandatory.
-   norefresh : set to "true" to disable auto refresh for this page.
-   secured : set to "true" to fail unless the caller is admin.
-             (deprecated: @permission should be used instead)
-   permission: if non-null, the page rendering fails unless the caller has the given permission
-   css :
-     specify path that starts from "/" for loading additional CSS stylesheet.
-     path is interprted as relative to the context root. e.g.,
-     <l:layout css="/plugin/mysuperplugin/css/myneatstyle.css">
--->
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler" xmlns:d="jelly:define" xmlns:l="/lib/layout">
+  <st:documentation>
+    Outer-most tag for a normal (non-AJAX) HTML rendering.
+    This is used with nested &lt;side-panel> and &lt;main-panel>
+    to form Hudson's basic HTML layout.
+
+    <st:attribute name="title" use="required">
+      Title of the HTML page. Rendered into &lt;title> tag.
+    </st:attribute>
+    <st:attribute name="norefresh">
+      If non-null, auto refresh is disabled on this page.
+      This is necessary for pages that include forms.
+    </st:attribute>
+    <st:attribute name="css" deprecated="true">
+      specify path that starts from "/" for loading additional CSS stylesheet.
+      path is interprted as relative to the context root. e.g.,
+      <pre>
+      &lt;l:layout css="/plugin/mysuperplugin/css/myneatstyle.css">
+      </pre>
+
+      This was originally added to allow plugins to load their stylesheets, but
+      plugins should now do so by inserting &lt;style> elements and/or &lt;script> elements
+      in &lt;l:header/> tag.
+    </st:attribute>
+    <st:attribute name="permission">
+      If given, this page is only made available to users that has the specified permission.
+      (The permission will be checked against the "it" object.)
+    </st:attribute>
+  </st:documentation>
 <st:header name="Expires" value="0" />
 <!-- Use st:header here rather than st:contentType because Jetty 5.x appears to ignore the latter. -->
 <st:header name="Content-Type" value="text/html;charset=UTF-8" />
diff --git a/core/src/main/resources/lib/layout/yui.jelly b/core/src/main/resources/lib/layout/yui.jelly
index 34007f003ff7ae2612b6aed648df18f2a9ee0657..d5d16d6fb785e227608fe4e5ddb083cb61bc5c94 100644
--- a/core/src/main/resources/lib/layout/yui.jelly
+++ b/core/src/main/resources/lib/layout/yui.jelly
@@ -1,10 +1,12 @@
-<!--
-  Load Yahoo UI module.
-
-  Attributes:
-    @module   module name to be loaded
-    @suffix   if loading beta module, use suffix='-beta'
--->
 <j:jelly xmlns:j="jelly:core" xmlns:st="jelly:stapler">
+  <st:documentation>
+    Load Yahoo UI module.
+    <st:attribute name="module" use="required">
+      YUI module name to load.
+    </st:attribute>
+    <st:attribute name="suffix">
+      if loading beta module, use suffix='-beta'
+    </st:attribute>
+  </st:documentation>
   <script src="${resURL}/scripts/yui/${module}/${module}${attrs.suffix}-${yuiSuffix}.js" />
 </j:jelly>
\ No newline at end of file