Flesh out documentation for .NET rules. Minor formatting changes to

csharp.bzl.

--
Change-Id: Ie2a98cafdd76a7d8994f25d280d18ec848732aaa
Reviewed-on: https://bazel-review.googlesource.com/#/c/2320/
MOS_MIGRATED_REVID=107987176

2 files changed, 250 insertions, 78 deletions

diff --git a/tools/build_defs/dotnet/README.md b/tools/build_defs/dotnet/README.md
index 0f8dd9ec7e..abe5cc9793 100644
--- a/tools/build_defs/dotnet/README.md
+++ b/tools/build_defs/dotnet/README.md
@@ -1,15 +1,30 @@
-Intro
-=====
+# C# Rules
+
+## Rules
+
+<div class="toc">
+  <h2>Rules</h2>
+  <ul>
+    <li><a href="#csharp_library">csharp_library</a></li>
+    <li><a href="#csharp_binary">csharp_binary</a></li>
+    <li><a href="#csharp_nunit_test">csharp_nunit_test</a></li>
+  </ul>
+</div>
+
+## Overview
 
 This is a minimal viable set of C# bindings for building csharp code with
 mono. It's still pretty rough but it works as a proof of concept that could
 grow into something more. If windows support ever happens for Bazel then this
 might become especially valuable.
 
-Rules
-=====
+## Setup
 
-* csharp\_library
+Copy the contents of the dotnet.WORKSPACE file into your WORKSPACE file.
+
+## Examples
+
+* `csharp_library`
 
         csharp_library(
             name="MyLib",
@@ -17,7 +32,7 @@ Rules
             deps=["//my/dependency:SomeLib"],
         )
 
-* csharp\_binary
+* `csharp_binary`
 
         csharp_binary(
             name="MyApp",
@@ -26,7 +41,7 @@ Rules
             deps=["//my/dependency:MyLib"],
         )
 
-* csharp\_nunit\_test
+* `csharp_nunit_test`
 
         csharp_nunit_test(
             name="MyApp",
@@ -34,44 +49,209 @@ Rules
             deps=["//my/dependency:MyLib"],
         )
 
-Shared attributes for all csharp rules
---------------------------------------
-
-<table class=table table-condensed table-bordered table-params">
-<colgroup>
-  <col class="col-param" />
-  <col class="param-description" />
-</colgroup>
-<thead>
-  <tr>
-    <th colspan="2">Attributes</th>
-  </tr>
-</thead>
-<tbody>
-<tr><td>name</td>string<td><td>Unique name for this rule</td></td>Required</td></tr>
-<tr><td>srcs</td>List of Labels<td><td>Csharp .cs or .resx files.</td></td>Required</td></tr>
-<tr><td>deps</td>List of Labels<td><td>Dependencies for this rule.</td></td>Optional</td></tr>
-<tr><td>warn</td>Int<td><td>Compiler warn level for this library. (Defaults to 4.)</td></td>optional</td></tr>
-<tr><td>csc</td>string<td><td>Override the default csharp compiler.</td></td>Optional</td></tr>
-</tbody>
-</table>
-
-Usage
-=====
-
-Copy the contents of the dotnet.WORKSPACE file into your WORKSPACE file.
-
-Things still missing:
-=====================
+## Things still missing:
 
 - Handle .resx files correctly.
 - .Net Modules
-- building documentation.
+- Conditionally building documentation.
 - Pulling Mono in through a mono.WORKSPACE file.
 
-Future nice to haves:
-=====================
+## Future nice to haves:
 
-- building csproj and sln files for VS and MonoDevelop.
+- Building csproj and sln files for VS and MonoDevelop.
 - Nuget Packaging
-- Windows .Net framwork support
+- Windows .NET framwork support
+
+<a name="csharp_library"></a>
+## csharp_library
+
+```python
+csharp_library(name, srcs, deps, warn=4, csc)
+```
+
+Builds a C# .NET library and its corresponding documentation.
+
+<table class="table table-condensed table-bordered table-params">
+  <colgroup>
+    <col class="col-param" />
+    <col class="param-description" />
+  </colgroup>
+  <thead>
+    <tr>
+      <th colspan="2">Attributes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>name</code></td>
+      <td>
+        <p><code>Name, required</code></p>
+        <p>Unique name for this rule</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>srcs</code></td>
+      <td>
+        <p><code>List of Labels; required</code></p>
+        <p>Csharp .cs or .resx files.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>deps</code></td>
+      <td>
+        <p><code>List of Labels; optional</code></p>
+        <p>Dependencies for this rule.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>warn</code></td>
+      <td>
+        <p><code>Int; optional; default is 4</code></p>
+        <p>Compiler warn level for this library. (Defaults to 4.)</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>csc</code></td>
+      <td>
+        <p><code>string; optional</code></p>
+        <p>Override the default csharp compiler.</p>
+        <p>
+          <strong>Note:</strong> This attribute may removed in future
+          versions.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<a name="csharp_binary"></a>
+## csharp_binary
+
+```python
+csharp_binary(name, srcs, deps, main_class, warn=4, csc)
+```
+
+Builds a C# .NET binary.
+
+<table class="table table-condensed table-bordered table-params">
+  <colgroup>
+    <col class="col-param" />
+    <col class="param-description" />
+  </colgroup>
+  <thead>
+    <tr>
+      <th colspan="2">Attributes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>name</code></td>
+      <td>
+        <p><code>Name, required</code></p>
+        <p>Unique name for this rule</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>srcs</code></td>
+      <td>
+        <p><code>List of Labels; required</code></p>
+        <p>Csharp .cs or .resx files.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>deps</code></td>
+      <td>
+        <p><code>List of Labels; optional</code></p>
+        <p>Dependencies for this rule.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>main_class</code></td>
+      <td>
+        <p><code>String; optional</code>
+        <p>Name of class with <code>main()</code> method to use as entry point.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>warn</code></td>
+      <td>
+        <p><code>Int; optional; default is 4</code></p>
+        <p>Compiler warn level for this binary. (Defaults to 4.)</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>csc</code></td>
+      <td>
+        <p><code>string; optional</code></p>
+        <p>Override the default csharp compiler.</p>
+        <p>
+          <strong>Note:</strong> This attribute may removed in future
+          versions.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<a name="csharp_nunit_test"></a>
+## csharp\_nunit\_test
+
+```python
+csharp_nunit_test(name, srcs, deps, warn=4, csc)
+```
+
+Builds a C# .NET test binary that uses the [NUnit](http://www.nunit.org/) unit
+testing framework.
+
+<table class="table table-condensed table-bordered table-params">
+  <colgroup>
+    <col class="col-param" />
+    <col class="param-description" />
+  </colgroup>
+  <thead>
+    <tr>
+      <th colspan="2">Attributes</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>name</code></td>
+      <td>
+        <p><code>Name, required</code></p>
+        <p>Unique name for this rule</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>srcs</code></td>
+      <td>
+        <p><code>List of Labels; required</code></p>
+        <p>Csharp .cs or .resx files.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>deps</code></td>
+      <td>
+        <p><code>List of Labels; optional</code></p>
+        <p>Dependencies for this rule.</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>warn</code></td>
+      <td>
+        <p><code>Int; optional; default is 4</code></p>
+        <p>Compiler warn level for this test. (Defaults to 4.)</p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>csc</code></td>
+      <td>
+        <p><code>string; optional</code></p>
+        <p>Override the default csharp compiler.</p>
+        <p>
+          <strong>Note:</strong> This attribute may removed in future
+          versions.
+        </p>
+      </td>
+    </tr>
+  </tbody>
+</table>
diff --git a/tools/build_defs/dotnet/csharp.bzl b/tools/build_defs/dotnet/csharp.bzl
index 297ca60303..2fcea4af15 100644
--- a/tools/build_defs/dotnet/csharp.bzl
+++ b/tools/build_defs/dotnet/csharp.bzl
@@ -38,8 +38,7 @@ def _make_csc_deps(deps, extra_files=[]):
     return struct(
         dlls = dlls + set(extra_files),
         refs = refs,
-        transitive_dlls = transitive_dlls,
-        )
+        transitive_dlls = transitive_dlls)
 
 def _get_libdirs(dlls, libdirs=[]):
     return [dep.dirname for dep in dlls] + libdirs
@@ -97,13 +96,11 @@ done
 
     content = content.format(
         nunit_exe=ctx.files._nunit_exe[0].path,
-        libs=" ".join(libs),
-        )
+        libs=" ".join(libs))
 
     ctx.file_action(
         output=ctx.outputs.executable,
-        content=content,
-        )
+        content=content)
 
 def _make_launcher(ctx, depinfo, output):
     content = """#!/bin/bash
@@ -121,13 +118,11 @@ done
 
     content = content.format(
         exe=output.short_path,
-        libs=" ".join(libs),
-        )
+        libs=" ".join(libs))
 
     ctx.file_action(
         output=ctx.outputs.executable,
-        content=content,
-        )
+        content=content)
 
 def _csc_get_output(ctx):
     output = None
@@ -146,8 +141,7 @@ def _csc_collect_inputs(ctx, extra_files=[]):
     return struct(
         depinfo=depinfo,
         inputs=inputs,
-        srcs=srcs,
-        )
+        srcs=srcs)
 
 def _csc_compile_action(ctx, assembly, all_outputs, collected_inputs, extra_refs=[]):
     csc_args = _make_csc_arglist(ctx, assembly, collected_inputs.depinfo, extra_refs=extra_refs)
@@ -161,13 +155,11 @@ def _csc_compile_action(ctx, assembly, all_outputs, collected_inputs, extra_refs
         progress_message = ("Compiling " +
                             ctx.label.package + ":" +
                             ctx.label.name))
-    return
 
 def _cs_runfiles(ctx, outputs, depinfo):
     return ctx.runfiles(
         files = outputs,
-        transitive_files = set(depinfo.dlls + depinfo.transitive_dlls) or None,
-        )
+        transitive_files = set(depinfo.dlls + depinfo.transitive_dlls) or None)
 
 
 def _csc_compile_impl(ctx):
@@ -226,32 +218,32 @@ def _cs_nunit_run_impl(ctx):
                   transitive_dlls = depinfo.dlls,
                   runfiles=runfiles)
 
-_COMMON_ATTRS={
-        # configuration fragment that specifies
-        "_flag_start": attr.string(default="-"),
-        # where the csharp compiler is.
-        "csc": attr.string(default=_MONO_UNIX_CSC),
-        # code dependencies for this rule.
-        # all dependencies must provide an out field.
-        "deps": attr.label_list(providers=["out", "target_type"]),
-        # source files for this target.
-        "srcs": attr.label_list(allow_files = FileType([".cs", ".resx"])),
-        # resources to use as dependencies.
-        # TODO(jeremy): "resources_deps": attr.label_list(allow_files=True),
-        #TODO(jeremy): # name of the module if you are creating a module.
-        #TODO(jeremy): "modulename": attri.string(),
-        # warn level to use
-        "warn": attr.int(default=4),
-        # define preprocessor symbols.
-        #TODO(jeremy): "define": attr.string_list(),
-    }
+_COMMON_ATTRS = {
+    # configuration fragment that specifies
+    "_flag_start": attr.string(default="-"),
+    # where the csharp compiler is.
+    "csc": attr.string(default=_MONO_UNIX_CSC),
+    # code dependencies for this rule.
+    # all dependencies must provide an out field.
+    "deps": attr.label_list(providers=["out", "target_type"]),
+    # source files for this target.
+    "srcs": attr.label_list(allow_files = FileType([".cs", ".resx"])),
+    # resources to use as dependencies.
+    # TODO(jeremy): "resources_deps": attr.label_list(allow_files=True),
+    #TODO(jeremy): # name of the module if you are creating a module.
+    #TODO(jeremy): "modulename": attri.string(),
+    # warn level to use
+    "warn": attr.int(default=4),
+    # define preprocessor symbols.
+    #TODO(jeremy): "define": attr.string_list(),
+}
 
 _LIB_ATTRS={"_target_type": attr.string(default="library")}
 
 _EXE_ATTRS={
-        "_target_type": attr.string(default="exe"),
-        # main class to use as entry point.
-        "main_class": attr.string(),
+    "_target_type": attr.string(default="exe"),
+    # main class to use as entry point.
+    "main_class": attr.string(),
 }
 
 _NUNIT_ATTRS={