Directives#

Each directive describes one kind of C# declaration. Write the signature as it appears in C# source, with any attributes and modifiers:

.. cs:function:: [Obsolete] public static Point Parse (string text)

The examples on this page describe a small Geometry library. Each example shows the reStructuredText, then the result.

Tip

Put .. default-domain:: cs at the top of a page to write .. class:: in place of .. cs:class::.

Namespaces#

The namespace directive sets the namespace of the declarations that follow it:

.. cs:namespace:: Geometry

The namespace stays set until the end of the page, or the next namespace directive. Clear it with .. cs:namespace:: None.

namespace-push nests a namespace in the current one, and namespace-pop returns to the namespace from before it:

.. cs:namespace-push:: Drawing

.. cs:class:: Canvas

.. cs:namespace-pop::

class Canvas#

The full name of Canvas is Geometry.Drawing.Canvas. Each namespace is a target for the :cs:namespace: role, unless the directive has the :no-index: option.

Types#

The class, struct, interface and record directives describe types. Nest the members of a type in its directive:

.. cs:class:: public abstract class Shape : IComparable<Shape>

   The base class of every shape.

   .. cs:function:: public abstract double Area ()

public abstract class Shape : IComparable<Shape>#

The base class of every shape.

public abstract double Area ()#

A generic type has generic parameters and constraints, and a type can have a primary constructor:

.. cs:class:: public class Layer<T>(string name) where T : Shape

.. cs:struct:: public readonly struct Point (double X, double Y)

.. cs:interface:: public interface IScalable

.. cs:record:: public record Size (double Width, double Height)

.. cs:record:: public record struct Bounds (Point Min, Point Max)

public class Layer<T> (string name) where T : Shape #

public readonly struct Point (double X, double Y)#

public interface IScalable#

public record Size (double Width, double Height)#

public record struct Bounds (Point Min, Point Max)#

.. cs:record:: takes a class or struct keyword, as in record struct. The inherits directive adds a base type to the type it is nested in:

.. cs:class:: public class Circle

   .. cs:inherits:: Shape

public class Circle#

: Shape

Enums#

The enum directive describes an enum, and enumerator describes each of its values:

.. cs:enum:: public Color : byte

   .. cs:enumerator:: Red = 1

   .. cs:enumerator:: Green = 2

public enum Color : byte #

Red = 1#

Green = 2#

Methods#

The function directive describes methods, constructors, finalizers and operators:

.. cs:class:: public class Polygon : Shape

   .. cs:function:: public Polygon (params Point[] points)

   .. cs:function:: public Polygon (IEnumerable<Point> points) : this(points.ToArray())

   .. cs:function:: public override double Area ()

   .. cs:function:: public bool TryGetPoint (int index, [NotNullWhen(true)] out Point? point)

   .. cs:function:: public T Find<T> (Func<Point, T> map) where T : notnull

   .. cs:function:: public static Polygon operator + (Polygon a, Point offset)

   .. cs:function:: public static explicit operator Point[] (Polygon polygon)

public class Polygon : Shape #

public Polygon (params Point[] points)#

public Polygon (IEnumerable<Point> points) : this(points.ToArray())#

public override double Area ()#

public bool TryGetPoint (int index, [NotNullWhen(true)] out Point? point)#

public T Find<T> (Func<Point, T> map) where T : notnull#

public static Polygon operator + (Polygon a, Point offset)#

public static explicit operator Point[] (Polygon polygon)#

Write several overloads in one directive, one signature on each line:

.. cs:function:: public void Scale (double factor)
                 public void Scale (double x, double y)

The delegate directive describes a delegate:

.. cs:delegate:: public delegate void ShapeChanged (Shape shape)

public delegate void ShapeChanged (Shape shape)#

Fields, Properties and Events#

The var, property and event directives describe fields, properties and events:

.. cs:class:: public class Grid

   .. cs:var:: public const int MaxSize = 1024

   .. cs:var:: private readonly int rows, columns

   .. cs:property:: public int Count { get; private set; }

   .. cs:property:: public double Spacing { get => field; set => field = Math.Max(value, 0); }

   .. cs:event:: public event EventHandler? Changed

public class Grid#

public const int MaxSize = 1024#

private readonly int rows#
private readonly int columns#

public int Count { get; private set; }#

public double Spacing { get; set; }#

public event EventHandler? Changed#

A field that declares several variables, as in int rows, columns, describes each variable. Accessors show their access level, and leave out their bodies.

Indexers#

The indexer directive describes an indexer:

.. cs:class:: public class Path

   .. cs:indexer:: public Point this[int index] { get; set; }

public class Path#

public Point this[int index] { get; set; }#

Attributes#

The attribute directive describes an attribute class, with its constructor parameters:

.. cs:attribute:: UnitsAttribute (string name)

UnitsAttribute (string name)#

Extension Blocks#

The extension directive describes a C# 14 extension block. Its members belong to the enclosing static class:

.. cs:class:: public static class ShapeExtensions

   .. cs:extension:: (Shape shape)

      .. cs:property:: public bool IsEmpty { get; }

public static class ShapeExtensions#

extension (Shape shape)

public bool IsEmpty { get; }#

The full name of IsEmpty is Geometry.ShapeExtensions.IsEmpty. The generic parameters of a block, as in <T>(IEnumerable<T> source), are not linked in its members.

Doc Fields#

Describe parameters, type parameters, return values and exceptions with field lists:

.. cs:function:: public static T Largest<T> (IReadOnlyList<T> shapes, int start = 0) where T : Shape

   :param shapes: The shapes to search.
   :param int start: The index to start at.
   :typeparam T: The type of shape.
   :returns: The shape with the largest area.
   :rtype: T
   :throws ArgumentOutOfRangeException: If start is past the end of the list.

public static T Largest<T> (IReadOnlyList<T> shapes, int start = 0) where T : Shape #

Parameters:

shapes – The shapes to search.
start (int) – The index to start at.

Type Parameters:

T – The type of shape.

Returns:

The shape with the largest area.

Return type:

T

Throws:

ArgumentOutOfRangeException – If start is past the end of the list.

The types in the type, rtype and throws fields link like the types in a signature.

Options#

Describe an object with options after its signature:

.. cs:function:: void Draw (Canvas canvas, Color color, int x, int y, int width, int height)
   :single-line-parameter-list:
   :no-index-entry:

Every directive that describes an object takes these options:

:no-index:: Leave the object out of the index and the domain, so references do not link to it.
:no-index-entry:: Leave the object out of the general index only.
:no-contents-entry:: Leave the object out of the table of contents.
:single-line-parameter-list:: Keep the parameters on one line, however long the signature.

namespace and namespace-push take only :no-index:, and namespace-pop takes no options.

A signature longer than the maximum_signature_line_length option of Sphinx puts each parameter on a line of its own.

Each object in a section gets an entry in the table of contents, with members nested in their types. The toc_object_entries_show_parents option of Sphinx sets how much of each name the entry shows.