From brian.nickel at gmail.com  Thu Jun 14 15:31:48 2007
From: brian.nickel at gmail.com (Brian Kerrick Nickel)
Date: Thu, 14 Jun 2007 12:31:48 -0700
Subject: [Mono-docs-list] Documentation Guidelines
Message-ID: <1181849508.4256.31.camel@localhost>

Hi,

Is there an official set of guidelines and formats for documenting .NET
libraries? One of the hardest things I've found about documenting my
stuff (and some Gtk# stuff) is that I'm not sure of the best way to
format stuff and I lack consistency.

I think it would be really helpful to have rules like:

   When describing a constructor use:
   Constructs and initializes a new instance of <see/> [...].
   
   Where [...] is "with default values"

   or a list describing parameters without using specific type names if
   possible, eg:
      "with a given message."
      "with a given IP address and port number."
      "with a given file name, seek position, and read style."
   
   OR describing the action the constructor will take with the
   parameters:
      "by reading values using the given file name, seek position, and
      read style."


I think guidelines like that would help the documentation process,
especially for new contributors.

- Brian


From binary.god at gmail.com  Fri Jun 29 00:57:21 2007
From: binary.god at gmail.com (Timothy Davis)
Date: Fri, 29 Jun 2007 00:57:21 -0400
Subject: [Mono-docs-list] Documentation Import format?
Message-ID: <B7E7F2A7-1C00-4040-853D-2D8C412B27F1@gmail.com>

Hello everyone,

I'm sitting here working on a small OS X app, and I had this idea.  I  
was wondering if it's feasible at all.

My app is a Mono Type Reflector for OS X, (GUI Screenshot -> http:// 
www.binarymethod.com/images/typereflex.png (not complete yet)) and I  
was wondering if there was a predetermined file format that I could  
export so that the user could upload it to the offical Mono docs?   
That way you could work on stuff offline and then online it later.

I see that when I goto the online docs page that it says users can  
edit and then upload...but I have yet to find an edit link or upload  
link.  Am I  missing something?

Thanks,
TD

Dawn's cold passion filters through the trees
In darkness I showed you ecstacy
In darkness I took you from this world
Light shall never fall upon your face again

 From spring I've waited for this winter's reap
I've watched you pass autumn's twilight yearning

Now with dawn I bring you eternal sleep
And silence all forever mourning...




-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.ximian.com/pipermail/mono-docs-list/attachments/20070629/db2cb868/attachment.html 

From valentin.sawadski at gmx.de  Sat Jun 30 11:53:55 2007
From: valentin.sawadski at gmx.de (Valentin Sawadski)
Date: Sat, 30 Jun 2007 15:53:55 +0000
Subject: [Mono-docs-list] Removal of the Edit Section from the Welcome Page
Message-ID: <1183218835.5084.11.camel@Pi1536.site>

Hello,

attached is a short patch which comments out the Edit-Box at the front
page of the online-documentation.

Hopefully this will stop confusing the users as they are looking for the
mentioned "Edit"-Button on the online-docs without any chance of
success.

Kind Regards,
Valentin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: WebDocs_Welcome.diff
Type: text/x-patch
Size: 845 bytes
Desc: not available
Url : http://lists.ximian.com/pipermail/mono-docs-list/attachments/20070630/cc338849/attachment.bin 

From jonpryor at vt.edu  Sat Jun 30 16:52:41 2007
From: jonpryor at vt.edu (Jonathan Pryor)
Date: Sat, 30 Jun 2007 16:52:41 -0400
Subject: [Mono-docs-list] Documentation Import format?
In-Reply-To: <B7E7F2A7-1C00-4040-853D-2D8C412B27F1@gmail.com>
References: <B7E7F2A7-1C00-4040-853D-2D8C412B27F1@gmail.com>
Message-ID: <1183236761.3845.6.camel@melchior.magi>

On Fri, 2007-06-29 at 00:57 -0400, Timothy Davis wrote:
> My app is a Mono Type Reflector for OS X, (GUI Screenshot
> -> http://www.binarymethod.com/images/typereflex.png (not complete
> yet)) and I was wondering if there was a predetermined file format
> that I could export so that the user could upload it to the offical
> Mono docs?  That way you could work on stuff offline and then online
> it later.

Yes, it's an XML dialect.  See:

http://www.mono-project.com/Monodocer
http://anonsvn.mono-project.com/source/trunk/monodoc/man/monodocer.1
http://anonsvn.mono-project.com/source/trunk/monodoc/tools/DocTest/en.expected/Mono.DocTest.Generic/MyList%602.xml

(The latter is an example XML file.  Real XML files are stored on
monodoc/class/ASSEMBLY-NAME/en/NAMESPACE/CLASS.xml.)

> I see that when I goto the online docs page that it says users can
> edit and then upload...but I have yet to find an edit link or upload
> link.  Am I  missing something?

You can edit and upload through the monodoc browser/editor.  Uploading
uses a SOAP service and its own custom dialect (which I'm not familiar
with); using the monodoc XML format (above) is what's stored in svn.

 - Jon

>