Welcome to mirror list, hosted at ThFree Co, Russian Federation.

github.com/mono/mono.git - Unnamed repository; edit this file 'description' to name the repository.
summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGonzalo Paniagua Javier <gonzalo.mono@gmail.com>2010-10-22 20:52:19 +0400
committerGonzalo Paniagua Javier <gonzalo.mono@gmail.com>2010-10-22 20:52:19 +0400
commitf8c9c8751290f47fa17fa5851ce97ddc9c443bf4 (patch)
tree46e4a8bc6c0a3996df0f0c78753519ebcc93572d /web/documentation
parent231527ee6286af554c59396037c8504a6564395e (diff)
Sniff, sniff
Remove the old (really) stuff to generate the website from makefiles.
Diffstat (limited to 'web/documentation')
-rw-r--r--web/documentation260
1 files changed, 0 insertions, 260 deletions
diff --git a/web/documentation b/web/documentation
deleted file mode 100644
index 40085e85126..00000000000
--- a/web/documentation
+++ /dev/null
@@ -1,260 +0,0 @@
-* 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>
-&lt;para&gt; &lt;/para&gt;
-</pre>
- Used to separate paragraphs.
-
-<pre>
-&lt;paramref name="param_name"/&gt;
-</pre>
- Used to reference a formal parameter to a function.
-
-<pre>
-&lt;see cref="T:SomeTypeName"/&gt;
-</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>
- &lt;see cref="T:System.Enum"/&gt;
-</pre>
-
-<pre>
-&lt;see cref="P:SomeTypeName.Property"/&gt;
-</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>
- &lt;see cref="P:System.Type.BaseType"/&gt;
-</pre>
-
-<pre>
-&lt;see cref="M:SomeTypeName.Method(type,type)"/&gt;
-</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>
- &lt;see cref="M:System.Object.ToString()"/&gt;
-</pre>
-
-<pre>
-&lt;see langword="keyword"/&gt;
-</pre>
- Use this to link to a keyword in the C# language, for
- example to link to `true', do:
-
-<pre>
- &lt;see langword="true"/&gt;
-</pre>
-
-<pre>
-&lt;example&gt; ... &lt;/example&gt;
-</pre>
- Use example to insert an example. The example can
- contain explanatory text and code.
-
-<pre>
-&lt;code lang="C#"&gt;.. &lt;/code&gt;
-</pre>
-
- Use this to provide a sample C# program, typically used
- within the &lt;example&gt; 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>
- &lt;code lang="C#" source="file.cs"&gt; &lt;/code&gt;
-</pre>
-
-<pre>
-&lt;item&gt;
-</pre>
-
-<pre>
-&lt;list type="bullet"&gt; &lt;/list&gt;
-</pre>
-
- Use this to create lists. Lists contains &lt;item&gt;
- elements which have to contain &lt;term&gt; containers.
-
-<pre>
-&lt;list type="table"&gt; &lt;/lits&gt;
- &lt;listheader&gt;
- &lt;term&gt;YOUR FIRST COLUMN&lt;/term&gt;
- &lt;description&gt;YOUR DESCRIPTION&lt;/description&gt;
- &lt;/listheader&gt;
-</pre>
- For two-column tables. Inside use:
-
-<pre>
-&lt;item&gt;
- &lt;term&gt;First&lt;/term&gt;
- &lt;description&gt;First descritpion&lt;/description&gt;
-&lt;/item&gt;
-&lt;item&gt;
- &lt;term&gt;Second&lt;/term&gt;
- &lt;description&gt;Second descirption&lt;/description&gt;
-&lt;/item&gt;
-</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:jbarn@httcb.net">jbarn@httcb.net</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.
-