[docs] Schema additions, and monodoc template updates.mono-3.4.0.202

- Expanded monodoc-ecma schema to support the 'preserve-mono' attribute, and the attribution tag.
- Added preserve-mono to several pieces of documentation that we would like to preserve across future automated documentation imports: CipherSuitesCallback, ServicePointManager, CultureInfo, Environment+SpecialFolder.xml
- XSL template changes for monodoc HTML generation to support <attribution>

12 files changed, 112 insertions, 27 deletions

diff --git a/mcs/class/System.Net.Http/Documentation/en/System.Net.Http/CFNetworkHandler.xml b/mcs/class/System.Net.Http/Documentation/en/System.Net.Http/CFNetworkHandler.xml
index cf35503c925..f714dec1a54 100644
--- a/mcs/class/System.Net.Http/Documentation/en/System.Net.Http/CFNetworkHandler.xml
+++ b/mcs/class/System.Net.Http/Documentation/en/System.Net.Http/CFNetworkHandler.xml
@@ -11,7 +11,7 @@
   <Interfaces />
   <Docs>
     <summary>An Http Message Handler for HttpClient that is powered by iOS/MacOS CFNetwork stack.</summary>
-    <remarks>
+    <remarks preserve-mono="true">
       <para>
 	This handler allows the HttpClient API to use Apple's
 	CFNetwork as the HTTP transport as opposed to the default
@@ -54,7 +54,7 @@ var client = new HttpClient (new CFNetworkHandler ());
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>Creates an instance of the CFNetwork-based http handler..</summary>
+        <summary preserve-mono="true">Creates an instance of the CFNetwork-based http handler..</summary>
         <remarks></remarks>
       </Docs>
     </Member>
@@ -69,7 +69,7 @@ var client = new HttpClient (new CFNetworkHandler ());
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Determines whether the request handler should follow redirects sent by the server.</summary>
+        <summary preserve-mono="true">Determines whether the request handler should follow redirects sent by the server.</summary>
         <value></value>
         <remarks></remarks>
       </Docs>
@@ -88,7 +88,7 @@ var client = new HttpClient (new CFNetworkHandler ());
         <Parameter Name="disposing" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <param name="disposing">True if this is being called from Dispose(), false if it is being invoked by the finalizer.</param>
+        <param name="disposing" preserve-mono="true">True if this is being called from Dispose(), false if it is being invoked by the finalizer.</param>
         <summary>Disposes this CFNetworkHandler.</summary>
         <remarks></remarks>
       </Docs>
@@ -116,11 +116,11 @@ var client = new HttpClient (new CFNetworkHandler ());
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="request">The request to send.</param>
-        <param name="cancellationToken">Cancelation token to cancel the operation.</param>
-        <summary>Sends the Http message asynchronously.</summary>
+        <param name="request" preserve-mono="true">The request to send.</param>
+        <param name="cancellationToken" preserve-mono="true">Cancelation token to cancel the operation.</param>
+        <summary preserve-mono="true">Sends the Http message asynchronously.</summary>
         <returns>Task representing the asynchronous operation.</returns>
-        <remarks>
+        <remarks preserve-mono="true">
 	  This method is invoked by the HttpClient, it is non-blocking.
 	</remarks>
       </Docs>
diff --git a/mcs/class/System/Documentation/en/System.Net/CipherSuitesCallback.xml b/mcs/class/System/Documentation/en/System.Net/CipherSuitesCallback.xml
index 9831fac80d9..ab9db499df8 100644
--- a/mcs/class/System/Documentation/en/System.Net/CipherSuitesCallback.xml
+++ b/mcs/class/System/Documentation/en/System.Net/CipherSuitesCallback.xml
@@ -16,10 +16,13 @@
     <ReturnType>System.Collections.Generic.IEnumerable&lt;System.String&gt;</ReturnType>
   </ReturnValue>
   <Docs>
-    <param name="protocol">To be added.</param>
-    <param name="allCiphers">To be added.</param>
-    <summary>To be added.</summary>
-    <returns>To be added.</returns>
-    <remarks>To be added.</remarks>
+    <param name="protocol" preserve-mono="true">The SSL/TLS protocol version used for the connection.</param>
+    <param name="allCiphers" preserve-mono="true">The ordered list of all supported cipher suites.</param>
+    <summary preserve-mono="true">You can provide your own code to filter/re-order the cipher suites to be used for client and/or server side SSL/TLS support.</summary>
+    <returns preserve-mono="true">The ordered list of all cipher suites you wish to support.</returns>
+    <remarks preserve-mono="true">
+      <para>This type is only available in Mono and Xamarin products.</para>
+      <para>See the <see cref="P:System.Net.ServicePointManager.ClientCipherSuitesCallback"/> property for examples of how this is used.</para>
+    </remarks>
   </Docs>
 </Type>
diff --git a/mcs/class/System/Documentation/en/System.Net/ServicePointManager.xml b/mcs/class/System/Documentation/en/System.Net/ServicePointManager.xml
index 6038d387402..d184730c1f2 100644
--- a/mcs/class/System/Documentation/en/System.Net/ServicePointManager.xml
+++ b/mcs/class/System/Documentation/en/System.Net/ServicePointManager.xml
@@ -92,9 +92,40 @@ instance. </para>
         <ReturnType>System.Net.CipherSuitesCallback</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary preserve-mono="true">You can filter and/or re-order the ciphers suites that will be sent to the SSL/TLS server by providing your own callback.</summary>
+	<value>Your custom delegate or null for the default behaviour.</value>
+        <remarks preserve-mono="true">
+	  <para>
+	    This mechanism cannot be used to add new ciphers. Undefined ciphers will be ignored. 
+	  </para>
+	  <para>
+	    This API is only available in Mono and Xamarin products.
+	  </para>
+	  <para>
+	    You can filter and/or re-order the ciphers suites that the SSL/TLS server
+	    will accept from a client. The first match for a supported client cipher suite
+	    will be used (so the order is important).
+	  </para>
+	  <example>
+	    <para>The following example removes weak (export) ciphers from the list that will be offered to the server.</para>
+	    <code lang="C#">
+ServicePointManager.ClientCipherSuitesCallback += (SecurityProtocolType p, IEnumerable&lt;string&gt; allCiphers) =&gt; {
+    return from cipher in allCiphers where !cipher.Contains ("EXPORT")
+    select cipher;
+};
+	  </code>
+	</example>
+	<example>
+	  <para>Example: Use AES128 (preference) or AES256 (allowed) but no other ciphers.</para>
+
+	  <code lang="C#">
+ServicePointManager.ClientCipherSuitesCallback += (SecurityProtocolType p, IEnumerable&lt;string&gt; allCiphers) =&gt; {
+    string prefix = p == SecurityProtocolType.Tls ? "TLS_" : "SSL_";
+    return new List&lt;string&gt; { prefix + "RSA_WITH_AES_128_CBC_SHA", prefix + "RSA_WITH_AES_256_CBC_SHA" };
+};
+    </code>
+	</example>
+      </remarks>
       </Docs>
     </Member>
     <Member MemberName="DefaultConnectionLimit">
diff --git a/mcs/class/corlib/Documentation/en/System.Globalization/CultureInfo.xml b/mcs/class/corlib/Documentation/en/System.Globalization/CultureInfo.xml
index 02e47b199b4..da5c10358db 100644
--- a/mcs/class/corlib/Documentation/en/System.Globalization/CultureInfo.xml
+++ b/mcs/class/corlib/Documentation/en/System.Globalization/CultureInfo.xml
@@ -28,7 +28,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>
+    <summary preserve-mono="true">
       <para>Represents locale information used by all culture dependendent types and methods.</para>
     </summary>
     <remarks>
@@ -244,7 +244,7 @@
         <summary>CultureInfo that represents the culture used by the current thread.</summary>
         <value>
         </value>
-        <remarks>Initial value for each thread is determined using following rules. When <see cref="P:System.Globalization.CultureInfo.DefaultThreadCurrentCulture" /> is set its value is used otherwise the framework uses <see cref="M:System.Globalization.CultureInfo.CreateSpecificCulture" /> method to map system locate to framework culture name. This operation may fail in rare cases when system locale is set to invalid value or to value which cannot be translated to framework culture name. In such case <see cref="P:System.Globalization.CultureInfo.InvariantCulture" /> values is used.</remarks>
+        <remarks preserve-mono="true">Initial value for each thread is determined using following rules. When <see cref="P:System.Globalization.CultureInfo.DefaultThreadCurrentCulture" /> is set its value is used otherwise the framework uses <see cref="M:System.Globalization.CultureInfo.CreateSpecificCulture" /> method to map system locate to framework culture name. This operation may fail in rare cases when system locale is set to invalid value or to value which cannot be translated to framework culture name. In such case <see cref="P:System.Globalization.CultureInfo.InvariantCulture" /> values is used.</remarks>
       </Docs>
     </Member>
     <Member MemberName="CurrentUICulture">
diff --git a/mcs/class/corlib/Documentation/en/System/Environment+SpecialFolder.xml b/mcs/class/corlib/Documentation/en/System/Environment+SpecialFolder.xml
index be42c1d89f9..c7b9110433a 100644
--- a/mcs/class/corlib/Documentation/en/System/Environment+SpecialFolder.xml
+++ b/mcs/class/corlib/Documentation/en/System/Environment+SpecialFolder.xml
@@ -342,7 +342,7 @@
       <MemberValue>Favorites</MemberValue>
       <Docs>
         <summary>The Favorites directory.  </summary>
-        <remarks>On Windows, the system favorite directory.   On MacOS X this is ~/Library/Favorites, and is empty for other operating systems.</remarks>
+        <remarks preserve-mono="true">On Windows, the system favorite directory.   On MacOS X this is ~/Library/Favorites, and is empty for other operating systems.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Fonts">
@@ -356,7 +356,7 @@
         <ReturnType>System.Environment+SpecialFolder</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>The fonts directory, on MacOS X this is ~/Library/Fonts, on other Unix operating systems it is ~/.fonts/</summary>
+        <summary preserve-mono="true">The fonts directory, on MacOS X this is ~/Library/Fonts, on other Unix operating systems it is ~/.fonts/</summary>
       </Docs>
     </Member>
     <Member MemberName="History">
@@ -392,7 +392,7 @@
       <MemberValue>InternetCache</MemberValue>
       <Docs>
         <summary>The Internet cache directory.</summary>
-        <remarks>The Internet cache directory on Windows.   On MacOS X this is the ~/Library/Caches directory, and not available on other operating systems.</remarks>
+        <remarks preserve-mono="true">The Internet cache directory on Windows.   On MacOS X this is the ~/Library/Caches directory, and not available on other operating systems.</remarks>
       </Docs>
     </Member>
     <Member MemberName="LocalApplicationData">
@@ -475,7 +475,7 @@
       </ReturnValue>
       <MemberValue>MyMusic</MemberValue>
       <Docs>
-        <summary>The music directory.  On MacOS X this is ~/Music.  On other Unix operating systems, this is either XDG_MUSIC_DIR from the environment, XDG_MUSIC_DIR as read from the "user-dirs.dirs" within the SpecialFolder.ApplicationData directory, or as a last resort, the directory named "Music" within the SpecialFolder.Personal directory (usually the home directory).</summary>
+        <summary preserve-mono="true">The music directory.  On MacOS X this is ~/Music.  On other Unix operating systems, this is either XDG_MUSIC_DIR from the environment, XDG_MUSIC_DIR as read from the "user-dirs.dirs" within the SpecialFolder.ApplicationData directory, or as a last resort, the directory named "Music" within the SpecialFolder.Personal directory (usually the home directory).</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -493,7 +493,7 @@
       </ReturnValue>
       <MemberValue>MyPictures</MemberValue>
       <Docs>
-        <summary>The pictures directory.  On MacOS X this is ~/Pictures.   On other Unix operating systems, this is either XDG_PICTURES_DIR from the environment, XDG_PICTURES_DIR as read from the "user-dirs.dirs" within the SpecialFolder.ApplicationData directory, or as a last resort, the directory named "Pictures" within the SpecialFolder.Personal directory (usually the home directory).</summary>
+        <summary preserve-mono="true">The pictures directory.  On MacOS X this is ~/Pictures.   On other Unix operating systems, this is either XDG_PICTURES_DIR from the environment, XDG_PICTURES_DIR as read from the "user-dirs.dirs" within the SpecialFolder.ApplicationData directory, or as a last resort, the directory named "Pictures" within the SpecialFolder.Personal directory (usually the home directory).</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -572,7 +572,7 @@
       <MemberValue>ProgramFiles</MemberValue>
       <Docs>
         <summary>Where program files are located.  </summary>
-        <remarks>The ProgramFiles directory on Windows, /Application on MacOS X and the empty string for other operating systems.</remarks>
+        <remarks preserve-mono="true">The ProgramFiles directory on Windows, /Application on MacOS X and the empty string for other operating systems.</remarks>
       </Docs>
     </Member>
     <Member MemberName="ProgramFilesX86">
diff --git a/mcs/class/monodoc/Makefile b/mcs/class/monodoc/Makefile
index 795cae98daf..6d4baf6ca46 100644
--- a/mcs/class/monodoc/Makefile
+++ b/mcs/class/monodoc/Makefile
@@ -65,6 +65,7 @@ RESOURCE_FILES = \
 	Resources/home.html               \
 	Resources/Lminus.gif              \
 	Resources/Lplus.gif               \
+	Resources/creativecommons.png     \
 	Resources/mdoc-html-format.xsl    \
 	Resources/mdoc-html-utils.xsl     \
 	Resources/mdoc-sections-css.xsl   \
@@ -99,6 +100,7 @@ LIB_MCS_FLAGS = \
 	/resource:Resources/home.html,home.html                           \
 	/resource:Resources/Lminus.gif,Lminus.gif                         \
 	/resource:Resources/Lplus.gif,Lplus.gif                           \
+	/resource:Resources/creativecommons.png,creativecommons.png       \
 	/resource:Resources/mdoc-html-format.xsl,mdoc-html-format.xsl     \
 	/resource:Resources/mdoc-html-utils.xsl,mdoc-html-utils.xsl       \
 	/resource:Resources/mdoc-sections-css.xsl,mdoc-sections-css.xsl   \
diff --git a/mcs/class/monodoc/Resources/base.css b/mcs/class/monodoc/Resources/base.css
index d264419b3cc..20175b43ae3 100644
--- a/mcs/class/monodoc/Resources/base.css
+++ b/mcs/class/monodoc/Resources/base.css
@@ -34,3 +34,12 @@ div.title {
 	font-style: italic;
 }
 
+.attributionlogo { 
+	display:none; 
+	float:right;
+}
+
+div:hover > .attributionlogo,p:hover > .attributionlogo,td:hover > .attributionlogo { 
+	display:inline; 
+	float:right;
+}
diff --git a/mcs/class/monodoc/Resources/creativecommons.png b/mcs/class/monodoc/Resources/creativecommons.png
new file mode 100644
index 00000000000..c558cbbe898
--- /dev/null
+++ b/mcs/class/monodoc/Resources/creativecommons.png
diff --git a/mcs/class/monodoc/Resources/mdoc-html-utils.xsl b/mcs/class/monodoc/Resources/mdoc-html-utils.xsl
index c8a84a84634..bc90f7b344c 100644
--- a/mcs/class/monodoc/Resources/mdoc-html-utils.xsl
+++ b/mcs/class/monodoc/Resources/mdoc-html-utils.xsl
@@ -1468,6 +1468,18 @@
 		</p>
 	</xsl:template>
 
+	<xsl:template match="attribution">
+		<a href="http://creativecommons.org/licenses/by/4.0/" class="attributionlogo">
+			<xsl:attribute name="title">
+				<xsl:choose>
+					<xsl:when test="@modified='false'"><xsl:value-of select="concat('This content is licensed Creative Commons By ', @from)" /></xsl:when>
+					<xsl:otherwise><xsl:value-of select="concat('This content has been modified under a Creative Commons license from ', @from)" /></xsl:otherwise>
+				</xsl:choose>
+			</xsl:attribute>
+		<img src="mdocimages/creativecommons.png" /> 
+		</a>
+	</xsl:template>
+
 	<xsl:template match="paramref">
 		<i><xsl:value-of select="@name"/>
 				<xsl:apply-templates/>
diff --git a/mcs/class/monodoc/monodoc-net_4_0.csproj b/mcs/class/monodoc/monodoc-net_4_0.csproj
index bd772bec0c8..7f56e7d3f37 100644
--- a/mcs/class/monodoc/monodoc-net_4_0.csproj
+++ b/mcs/class/monodoc/monodoc-net_4_0.csproj
@@ -516,7 +516,8 @@
     <Compile Include="Monodoc\storage\UncompiledDocStorage.cs" />

     <Compile Include="Monodoc\storage\ZipStorage.cs" />

     <Compile Include="Monodoc\Tree.cs" />

-    <Compile Include="Monodoc\TypeUtils.cs" />
  </ItemGroup>

+    <Compile Include="Monodoc\TypeUtils.cs" />

+  </ItemGroup>

   <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 

        Other similar extension points exist, see Microsoft.Common.targets.

   <Target Name="BeforeBuild">

@@ -587,6 +588,9 @@
     <EmbeddedResource Include="Resources/home.html">

       <LogicalName>home.html</LogicalName>

     </EmbeddedResource>

+    <EmbeddedResource Include="Resources/creativecommons.png">

+      <LogicalName>creativecommons.png</LogicalName>

+    </EmbeddedResource>

     <EmbeddedResource Include="Resources/Lminus.gif">

       <LogicalName>Lminus.gif</LogicalName>

     </EmbeddedResource>

diff --git a/mcs/class/monodoc/monodoc-net_4_5.csproj b/mcs/class/monodoc/monodoc-net_4_5.csproj
index e09884e01c9..90e30148794 100644
--- a/mcs/class/monodoc/monodoc-net_4_5.csproj
+++ b/mcs/class/monodoc/monodoc-net_4_5.csproj
@@ -516,7 +516,8 @@
     <Compile Include="Monodoc\storage\UncompiledDocStorage.cs" />

     <Compile Include="Monodoc\storage\ZipStorage.cs" />

     <Compile Include="Monodoc\Tree.cs" />

-    <Compile Include="Monodoc\TypeUtils.cs" />
  </ItemGroup>

+    <Compile Include="Monodoc\TypeUtils.cs" />

+  </ItemGroup>

   <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 

        Other similar extension points exist, see Microsoft.Common.targets.

   <Target Name="BeforeBuild">

@@ -587,6 +588,9 @@
     <EmbeddedResource Include="Resources/home.html">

       <LogicalName>home.html</LogicalName>

     </EmbeddedResource>

+    <EmbeddedResource Include="Resources/creativecommons.png">

+      <LogicalName>creativecommons.png</LogicalName>

+    </EmbeddedResource>

     <EmbeddedResource Include="Resources/Lminus.gif">

       <LogicalName>Lminus.gif</LogicalName>

     </EmbeddedResource>

@@ -744,4 +748,4 @@
       <LogicalName>treebg.png</LogicalName>

     </EmbeddedResource>

   </ItemGroup>

-</Project>
+</Project>

diff --git a/mcs/tools/mdoc/Resources/monodoc-ecma.xsd b/mcs/tools/mdoc/Resources/monodoc-ecma.xsd
index 7755b2c6e86..b0a64a14dce 100644
--- a/mcs/tools/mdoc/Resources/monodoc-ecma.xsd
+++ b/mcs/tools/mdoc/Resources/monodoc-ecma.xsd
@@ -12,6 +12,10 @@ add masterdoc support?
 <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
   <!-- define attributes -->
+  <xs:attribute name="preserve-mono" type="xs:string" />
+  <xs:attribute name="license" type="xs:string" />
+  <xs:attribute name="from" type="xs:string" />
+  <xs:attribute name="modified" type="xs:boolean" />
   <xs:attribute name="argnames" type="xs:string" />
   <xs:attribute name="cref" type="xs:string" />
   <xs:attribute name="Deprecated" type="xs:boolean" />
@@ -564,7 +568,9 @@ add masterdoc support?
         <xs:element ref="SPAN" />
         <xs:element ref="typeparamref" />
         <xs:element ref="whitespace" />
+        <xs:element ref="attribution" />
       </xs:choice>
+      <xs:attribute ref="preserve-mono" />
       <xs:attribute ref="name" use="required" />
     </xs:complexType>
   </xs:element>
@@ -633,7 +639,17 @@ add masterdoc support?
         <xs:element ref="list" />
         <xs:element ref="SPAN" />
         <xs:element ref="typeparamref" />
+        <xs:element ref="attribution" />
       </xs:choice>
+      <xs:attribute ref="preserve-mono" />
+    </xs:complexType>
+  </xs:element>
+
+  <xs:element name="attribution">
+    <xs:complexType mixed="true">
+      <xs:attribute ref="license" />
+      <xs:attribute ref="from" />
+      <xs:attribute ref="modified" />
     </xs:complexType>
   </xs:element>
 
@@ -653,7 +669,9 @@ add masterdoc support?
         <xs:element ref="typeparamref" />
         <xs:element ref="ul" />
         <xs:element ref="whitespace" />
+        <xs:element ref="attribution" />
       </xs:choice>
+      <xs:attribute ref="preserve-mono" />
     </xs:complexType>
   </xs:element>
 
@@ -738,7 +756,9 @@ add masterdoc support?
         <xs:element ref="typeparamref" />
         <xs:element ref="ul" />
         <xs:element ref="list" />
+        <xs:element ref="attribution" />
       </xs:choice>
+      <xs:attribute ref="preserve-mono" />
     </xs:complexType>
   </xs:element>