mirror of
https://github.com/BepInEx/mono.git
synced 2026-11-17 11:21:39 -10:00
261 lines
8.6 KiB
Plaintext
261 lines
8.6 KiB
Plaintext
* Documentation
|
|
|
|
Although most of the concepts from Microsoft.NET can
|
|
be applied to the completed Mono platform, we do need to
|
|
have a complete set of free documentation written specifically
|
|
for Mono.
|
|
|
|
The documentation license we have chosen is the GNU Free
|
|
Documentation License (FDL), the standard for most documents
|
|
in the free software world.
|
|
|
|
We need documentation on a number of topics:
|
|
|
|
<ul>
|
|
|
|
* The development tools (compilers, assembler tools,
|
|
language reference, design time features): these
|
|
live in the `monodoc' CVS module.
|
|
|
|
* Frequently Asked Question compilations.
|
|
|
|
* HOWTO documents.
|
|
|
|
* The Class Libraries (Both the original .NET class
|
|
libraries as well as the class libraries produced by
|
|
the project).
|
|
|
|
* Tutorials on Mono and the specifics of running it
|
|
(The <a href="http://www.monohispano.org">Mono
|
|
Hispano</a> team has produced lots of <a
|
|
href="http://www.monohispano.org/tutoriales.php">tutorials
|
|
in spanish</a>
|
|
|
|
* A guide to Mono as compared to the Microsoft.NET
|
|
Framework SDK
|
|
|
|
</ul>
|
|
|
|
* Class Library documentation
|
|
|
|
We are moving to a new setup for documenting the class libraries,
|
|
and you can read about it <a href="classlib-doc.html">here</a>.
|
|
|
|
There are two classes of documentation: free documentation for
|
|
existing .NET classes and documentation for the classes that
|
|
we have developed on top of .NET.
|
|
|
|
There is a large body of documentation that came from the ECMA
|
|
standarization effort that has been checked into CVS. It does
|
|
not contain everything Mono and .NET have, so they need to be
|
|
updated and augmented.
|
|
|
|
** Gtk# documentation
|
|
|
|
We also have a large body of class libraries that are specific
|
|
to Mono, for example the documentation for Gtk#.
|
|
|
|
We have checked in stub documentation for Gtk# into the CVS
|
|
repository (on gtk-sharp/doc) and we need volunteers to help
|
|
populate the documentation for it. Since Gtk# is a wrapper
|
|
for Gtk, plenty of documentation exists in the <a
|
|
href="http://developer.gnome.org/doc/API">Gnome developer
|
|
site</a>.
|
|
|
|
To get started:
|
|
|
|
You need to download Gtk# from the CVS repository. The module
|
|
name is `gtk-sharp'. You can obtain a copy from both the CVS
|
|
repository or the anonymous CVS repository.
|
|
|
|
To pull your copy type:
|
|
|
|
<pre>
|
|
cvs co gtk-sharp
|
|
</pre>
|
|
Documentation lives in gtk-sharp/doc/en. The "en" indicates the
|
|
English language, the first one we are targeting. We can later
|
|
do translations, but for now we are focusing on a single
|
|
language.
|
|
|
|
In that directory you will find the documentation organized by
|
|
namespaces. One directory per namespace. In the directories
|
|
you will find one XML file per class that needs to be
|
|
documented. The mission is to fill in the data with useful
|
|
information. Feel free to grab liberally information from the
|
|
Gtk documentation from:
|
|
|
|
<a href="http://developer.gnome.org/doc/API/">http://developer.gnome.org/doc/API/</a>
|
|
|
|
Of course, the API does not apply directly. It only applies at
|
|
a foundational level, so you can not really just copy and
|
|
paste. Summaries, and remarks sections can probably be lifted
|
|
with little or no effort.
|
|
|
|
Gtk# uses properties to represent get/set operations in the C
|
|
API, so you can also use some bits from there.
|
|
|
|
Most of the documentation contains already place holders for
|
|
text, we use the internationally approved phrase for this
|
|
purpose, `To be added'. So the quest is to remove all of the
|
|
"To be added" strings with information with resembles as closely
|
|
as possible the toolkit reality.
|
|
|
|
*** The pieces to be filled.
|
|
|
|
Summaries are one or two line descriptions of the element
|
|
(class, struct, interface, method, field, event, delegate), and
|
|
its used to render summary pages. So it has to be short.
|
|
|
|
The "remarks" section is used to describe in detail the element.
|
|
|
|
**** Tags.
|
|
|
|
As you document Gtk# you will have a number of tags that you can
|
|
use inside the summary and remarks sections, these are:
|
|
|
|
<pre>
|
|
<para> </para>
|
|
</pre>
|
|
Used to separate paragraphs.
|
|
|
|
<pre>
|
|
<paramref name="param_name"/>
|
|
</pre>
|
|
Used to reference a formal parameter to a function.
|
|
|
|
<pre>
|
|
<see cref="T:SomeTypeName"/>
|
|
</pre>
|
|
Use this to reference a type, this will include an hyper
|
|
link to the page for type SomeTypeName.
|
|
|
|
For example, to reference "System.Enum", do:
|
|
|
|
<pre>
|
|
<see cref="T:System.Enum"/>
|
|
</pre>
|
|
|
|
<pre>
|
|
<see cref="P:SomeTypeName.Property"/>
|
|
</pre>
|
|
Use this to reference a property, this will include an hyper
|
|
link to the page for the property `Property' of type `SomeTypeName'.
|
|
|
|
For example, to reference the BaseType property in System.Type, do:
|
|
|
|
<pre>
|
|
<see cref="P:System.Type.BaseType"/>
|
|
</pre>
|
|
|
|
<pre>
|
|
<see cref="M:SomeTypeName.Method(type,type)"/>
|
|
</pre>
|
|
Use this to reference a method, this will include an hyper
|
|
link to the page for the method `Method' of type `SomeTypeName'.
|
|
|
|
For example, to reference the ToString method in System.Object, do:
|
|
|
|
<pre>
|
|
<see cref="M:System.Object.ToString()"/>
|
|
</pre>
|
|
|
|
<pre>
|
|
<see langword="keyword"/>
|
|
</pre>
|
|
Use this to link to a keyword in the C# language, for
|
|
example to link to `true', do:
|
|
|
|
<pre>
|
|
<see langword="true"/>
|
|
</pre>
|
|
|
|
<pre>
|
|
<example> ... </example>
|
|
</pre>
|
|
Use example to insert an example. The example can
|
|
contain explanatory text and code.
|
|
|
|
<pre>
|
|
<code lang="C#">.. </code>
|
|
</pre>
|
|
|
|
Use this to provide a sample C# program, typically used
|
|
within the <example> tags.
|
|
|
|
When providing examples, try to provide a full example,
|
|
we would like to be able to have a button to compile and
|
|
run samples embedded into the documentation, or pop up
|
|
an editor to let the user play with the sample.
|
|
|
|
You can link to an example like this:
|
|
|
|
<pre>
|
|
<code lang="C#" source="file.cs"> </code>
|
|
</pre>
|
|
|
|
<pre>
|
|
<item>
|
|
</pre>
|
|
|
|
<pre>
|
|
<list type="bullet"> </list>
|
|
</pre>
|
|
|
|
Use this to create lists. Lists contains <item>
|
|
elements which have to contain <term> containers.
|
|
|
|
<pre>
|
|
<list type="table"> </lits>
|
|
<listheader>
|
|
<term>YOUR FIRST COLUMN</term>
|
|
<description>YOUR DESCRIPTION</description>
|
|
</listheader>
|
|
</pre>
|
|
For two-column tables. Inside use:
|
|
|
|
<pre>
|
|
<item>
|
|
<term>First</term>
|
|
<description>First descritpion</description>
|
|
</item>
|
|
<item>
|
|
<term>Second</term>
|
|
<description>Second descirption</description>
|
|
</item>
|
|
</pre>
|
|
|
|
** Words of warning.
|
|
|
|
A few words of warning and advice for class documentors:
|
|
|
|
A well-documented API can ease hours of frustration; as Mono
|
|
matures, robust and complete class library documentation will
|
|
become increasingly important. As you write API documentation,
|
|
whether it is embedded in source files or in external Monodoc XML,
|
|
please keep the following in mind:
|
|
|
|
Plagarism, even if it's unintentional, is a Bad Thing(TM).
|
|
Microsoft's .NET Framework Class Library documentation is an
|
|
excellent resource for understanding the behavior and properties of
|
|
a type, and a lot of hard work went in to creating this (copyrighted)
|
|
resource. Please don't copy from Microsoft's reference when
|
|
documenting a type.
|
|
|
|
To avoid this, I (<a href="mailto:[email protected]">[email protected]</a>)
|
|
suggest that you read the complete Microsoft documentation for a type,
|
|
ponder it for a while, and write the Mono documentation in your own
|
|
words. While it's certainly okay to refer to the Microsoft
|
|
documentation to clarify your understanding of behavior or properties,
|
|
please don't open the Microsoft docs and refer to them for each member
|
|
you document.
|
|
|
|
The best way of documenting is to read our source code
|
|
implementation and explain in your own words what our implementation
|
|
does, and what the user can do with it.
|
|
|
|
There's a lot of domain expertise among the class library contributors;
|
|
let's put the same personal stamp on the class library documentation
|
|
that we have on the class libraries themselves.
|
|
|