Better doc strings.

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Better doc strings.

Brad Byrd
I'm trying to provide better documentation for some C# classes that are called from Python.  Ideally, I'd like to markup my class in C#, either with the standard XML comments or with something like a [PythonDocAttribute], and have this documentation show up as the __doc__ string for the method or class in Python.  That way, the clients of my wrapped objects will see nice tool-tips on my classes as they code away in their IDE.

So, is this easily done?  Has anyone else crossed this bridge before?  Does something already exist that would work before I start hacking on the Python.NET source?

(Also, are the archives of the list searchable somewhere?  I just saw clickable-by-month archives, not searchable.)

Thanks,

Brad...

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Better doc strings.

Mark McMahon-2
Hi Brad,

No idea regarding your coding problem :-/

But your searching problem is easy...
Google allows you to specify a 'site' to restrict searches to. The following will search the archives for "__doc__"
        site:mail.python.org/pipermail/pythondotnet __doc__
(generating this URL)
http://www.google.com.sg/search?q=site%3Amail.python.org%2Fpipermail%2Fpythondotnet%2F+__doc

I guess other search engines may have something similar.

Hope that helps
  Mark


-----Original Message-----
From: pythondotnet-bounces+mark.mcmahon=[hidden email] [mailto:pythondotnet-bounces+mark.mcmahon=[hidden email]] On Behalf Of Brad Byrd
Sent: Tuesday, March 29, 2011 1:45 AM
To: [hidden email]
Subject: [Python.NET] Better doc strings.

I'm trying to provide better documentation for some C# classes that are called from Python.  Ideally, I'd like to markup my class in C#, either with the standard XML comments or with something like a [PythonDocAttribute], and have this documentation show up as the __doc__ string for the method or class in Python.  That way, the clients of my wrapped objects will see nice tool-tips on my classes as they code away in their IDE.

So, is this easily done?  Has anyone else crossed this bridge before?  Does something already exist that would work before I start hacking on the Python.NET source?

(Also, are the archives of the list searchable somewhere?  I just saw clickable-by-month archives, not searchable.)

Thanks,

Brad...

_________________________________________________
Python.NET mailing list - [hidden email] http://mail.python.org/mailman/listinfo/pythondotnet
_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Better doc strings.

Barton
In reply to this post by Brad Byrd
1) That's a very interesting proposition... Currently, the python
wrapper seems to overwrite any public attributes named __doc__. I'd
suggest a change that only writes that attr on the wrapped object if it
doesn't already exist in order for C# classes to get __doc__ strings in
the sort term.
[PythonDocAttribute] seems like the best answer for the long term.

2) The PythonDotNet Archives
(http://mail.python.org/pipermail/pythondotnet/) gives an OK overview
when you click on the [Subject] for each month.

On 03/28/2011 10:44 AM, Brad Byrd wrote:

> I'm trying to provide better documentation for some C# classes that are called from Python.  Ideally, I'd like to markup my class in C#, either with the standard XML comments or with something like a [PythonDocAttribute], and have this documentation show up as the __doc__ string for the method or class in Python.  That way, the clients of my wrapped objects will see nice tool-tips on my classes as they code away in their IDE.
>
> So, is this easily done?  Has anyone else crossed this bridge before?  Does something already exist that would work before I start hacking on the Python.NET source?
>
> (Also, are the archives of the list searchable somewhere?  I just saw clickable-by-month archives, not searchable.)
>
> Thanks,
>
> Brad...
>
> _________________________________________________
> Python.NET mailing list - [hidden email]
> http://mail.python.org/mailman/listinfo/pythondotnet
>

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Better doc strings.

Brad Byrd
In reply to this post by Mark McMahon-2
Thanks, that did the trick for searching the archives.  (I forgot that you could do that with Google.)

Unfortunately, it doesn't look like anyone else in the archives has asked this question before.

Brad...


-----Original Message-----
From: Mark McMahon [mailto:[hidden email]]
Sent: Tuesday, March 29, 2011 9:02 PM
To: Brad Byrd; [hidden email]
Subject: RE: Better doc strings.

Hi Brad,

No idea regarding your coding problem :-/

But your searching problem is easy...
Google allows you to specify a 'site' to restrict searches to. The following will search the archives for "__doc__"
        site:mail.python.org/pipermail/pythondotnet __doc__
(generating this URL)
http://www.google.com.sg/search?q=site%3Amail.python.org%2Fpipermail%2Fpythondotnet%2F+__doc

I guess other search engines may have something similar.

Hope that helps
  Mark


-----Original Message-----
From: pythondotnet-bounces+mark.mcmahon=[hidden email] [mailto:pythondotnet-bounces+mark.mcmahon=[hidden email]] On Behalf Of Brad Byrd
Sent: Tuesday, March 29, 2011 1:45 AM
To: [hidden email]
Subject: [Python.NET] Better doc strings.

I'm trying to provide better documentation for some C# classes that are called from Python.  Ideally, I'd like to markup my class in C#, either with the standard XML comments or with something like a [PythonDocAttribute], and have this documentation show up as the __doc__ string for the method or class in Python.  That way, the clients of my wrapped objects will see nice tool-tips on my classes as they code away in their IDE.

So, is this easily done?  Has anyone else crossed this bridge before?  Does something already exist that would work before I start hacking on the Python.NET source?

(Also, are the archives of the list searchable somewhere?  I just saw clickable-by-month archives, not searchable.)

Thanks,

Brad...

_________________________________________________
Python.NET mailing list - [hidden email] http://mail.python.org/mailman/listinfo/pythondotnet
_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Searchable Achive

Barton
In reply to this post by Brad Byrd
Nabble works really well.  For the moment, still on old.nabble:
http://old.nabble.com/Python---pythondotnet-f2969.html


On 3/28/2011 10:44 AM, Brad Byrd wrote:

> (Also, are the archives of the list searchable somewhere?  I just saw clickable-by-month archives, not searchable.)
>
> Thanks,
>
> Brad...
>
> _________________________________________________
> Python.NET mailing list - [hidden email]
> http://mail.python.org/mailman/listinfo/pythondotnet
>
_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Searchable Achive

Glenn Ramsey-2
You can also search with Google using site:mail.python.org/pipermail/pythondotnet/

On 18/04/11 06:35, Barton wrote:

> Nabble works really well.  For the moment, still on old.nabble:
> http://old.nabble.com/Python---pythondotnet-f2969.html
>
>
> On 3/28/2011 10:44 AM, Brad Byrd wrote:
>> (Also, are the archives of the list searchable somewhere?  I just saw
>> clickable-by-month archives, not searchable.)
>>
>> Thanks,
>>
>> Brad...

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Better doc strings.

Barton
In reply to this post by Brad Byrd
I just pushed the initial DocStringAttribute mods to the trunk:

* Python.Runtime now exposes a public class called DocStringAttribute
with usage = AttributeTargets.All

* Decorating .NET classes and methods has passed initial tests on Mono.

### test.cs ##
using System;
using System.Runtime.InteropServices;
using Python.Runtime;

namespace PinvokeTest
{
        [DocStringAttribute("Interface class to external functions.")]
        public class Invoke {
               
                [DocStringAttribute("External funtion simulation: WriteToFile(char)
will write a char to the terminal.")]
          public static void WriteToFile(char arg) {
              Console.WriteLine("Writing {0}", arg);
                         return;
                }
        }
}


## test.py ##
import clr
clr.AddReference("SimpleLibTest")   # the name of the .NET or Mono assembly
import PinvokeTest
from PinvokeTest import Invoke      # .NET or Mono namespace maps to a
python module
                                     # so grab the class from there
using import
Invoke.WriteToFile('a')             # Now call a method on the class
print "Function docstring:",
print Invoke.WriteToFile.__doc__
print "Class docstring:", Invoke.__doc__
i = Invoke()
print "Instance docstring:", i.__doc__



On 03/28/2011 10:44 AM, Brad Byrd wrote:
I'm trying to provide better documentation for some C# classes that are
called from Python.  Ideally, I'd like to markup my class in C#, either
with the standard XML comments or with something like a
[PythonDocAttribute], and have this documentation show up as the __doc__
string for the method or class in Python.  That way, the clients of my
wrapped objects will see nice tool-tips on my classes as they code away
in their IDE.

So, is this easily done?  Has anyone else crossed this bridge before?
Does something already exist that would work before I start hacking on
the Python.NET source?

(Also, are the archives of the list searchable somewhere?  I just saw
clickable-by-month archives, not searchable.)

Thanks,

Brad...

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet
Reply | Threaded
Open this post in threaded view
|

Re: Better doc strings.

Tribble, Brett
Well done sir!

-----Original Message-----
From: pythondotnet-bounces+btribble=[hidden email] [mailto:pythondotnet-bounces+btribble=[hidden email]] On Behalf Of Barton
Sent: Saturday, April 23, 2011 4:05 PM
To: Brad Byrd
Cc: [hidden email]
Subject: Re: [Python.NET] Better doc strings.

I just pushed the initial DocStringAttribute mods to the trunk:

* Python.Runtime now exposes a public class called DocStringAttribute
with usage = AttributeTargets.All

* Decorating .NET classes and methods has passed initial tests on Mono.

### test.cs ##
using System;
using System.Runtime.InteropServices;
using Python.Runtime;

namespace PinvokeTest
{
        [DocStringAttribute("Interface class to external functions.")]
        public class Invoke {
               
                [DocStringAttribute("External funtion simulation: WriteToFile(char)
will write a char to the terminal.")]
          public static void WriteToFile(char arg) {
              Console.WriteLine("Writing {0}", arg);
                         return;
                }
        }
}


## test.py ##
import clr
clr.AddReference("SimpleLibTest")   # the name of the .NET or Mono assembly
import PinvokeTest
from PinvokeTest import Invoke      # .NET or Mono namespace maps to a
python module
                                     # so grab the class from there
using import
Invoke.WriteToFile('a')             # Now call a method on the class
print "Function docstring:",
print Invoke.WriteToFile.__doc__
print "Class docstring:", Invoke.__doc__
i = Invoke()
print "Instance docstring:", i.__doc__



On 03/28/2011 10:44 AM, Brad Byrd wrote:
I'm trying to provide better documentation for some C# classes that are
called from Python.  Ideally, I'd like to markup my class in C#, either
with the standard XML comments or with something like a
[PythonDocAttribute], and have this documentation show up as the __doc__
string for the method or class in Python.  That way, the clients of my
wrapped objects will see nice tool-tips on my classes as they code away
in their IDE.

So, is this easily done?  Has anyone else crossed this bridge before?
Does something already exist that would work before I start hacking on
the Python.NET source?

(Also, are the archives of the list searchable somewhere?  I just saw
clickable-by-month archives, not searchable.)

Thanks,

Brad...

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet

_________________________________________________
Python.NET mailing list - [hidden email]
http://mail.python.org/mailman/listinfo/pythondotnet