From 43c0518a41fc169b9fe6f1682e03cfa2fed38d68 Mon Sep 17 00:00:00 2001
From: kohsuke <kohsuke@71c3de6d-444a-0410-be80-ed276b4c234a>
Date: Tue, 6 Jan 2009 05:23:17 +0000
Subject: [PATCH] added documentation.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@14188 71c3de6d-444a-0410-be80-ed276b4c234a
---
 .../WindowsInstallerLink/_restart.jelly       |  2 +-
 core/src/main/resources/lib/form/submit.jelly | 11 +++--
 .../main/resources/lib/layout/header.jelly    |  5 +++
 .../main/resources/lib/layout/layout.jelly    | 43 ++++++++++++-------
 core/src/main/resources/lib/layout/yui.jelly  | 16 ++++---
 5 files changed, 51 insertions(+), 26 deletions(-)

diff --git a/core/src/main/resources/hudson/lifecycle/WindowsInstallerLink/_restart.jelly b/core/src/main/resources/hudson/lifecycle/WindowsInstallerLink/_restart.jelly
index f05f1098e8..320325c35b 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 dbc37b0f9e..72000de18e 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 90f27a9dca..8da2dbb8f1 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 49e8ff2087..7b80b6a045 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 34007f003f..d5d16d6fb7 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
-- 
GitLab