Doc_strings Storage

[RIGHT_THEN]

Charles,

Are doc strings stored within the code or is it planned to be implemented in a seperate xml file
like c# comments, -doc option produces html. so does one has to read html to recover doc-strings??

i propose that doc-strings be implanted within the programm as attributes on c# side or are they allready.so that one can recover them programmatically for instance

def func
  """ def doc-string"""

on csharp side

Code: Select all

[CobraDocStringAttribute("def doc-string")]
func()
{}

so while using the assembly one can get it logically like this

Code: Select all

if method has CobraDocStringAttribute
get DocString

It would be good for future interpreters to see what something means.

and while we are at it why not introduce another Attribute Like CobraNonDocStringComment
for single line and multiline comments when they occur above or as you like below anything

and if you think of code bloat then there could be a commanline option to not include doc-strings.

so what do you think should i push a ticket?

Thanking_You
RIGHT_THEN

[Charles]

These are two separate requests. One to put doc strings in an attribute. One to put some select comments in an attribute.

Regarding the first, sounds fine to me. I presume .NET does not already have an attribute for this since their approach is to push C# doc comments to an XML file--but I haven't really researched it.

You can open a ticket if you want (first checking to see if there already is one).

It may also be useful to consider pushing out the kind of XML that C# does so that .NET doc tools can be used. But I see your point about the utility of making the docs "ride along" with the code.

I'm skeptical of the value of putting some comments (and not others) in attributes. Comments are supposed to be for people reading the implementation. If you want to read them, you should look at the source.

[torial]

I think a scenario that RIGHT_THEN's idea would work well with is something akin to the python interpreter, where you can type help({something}) to get the doc string for that {something}.

Not sure if that is what RIGHT_THEN wants it before, but that was the first use case that came to mind

Regarding doing stuff like the C# XML comments, there are a lot of great tools for handling that sort of output. Sandcastle coupled with the Sandcastle Help File Builder (http://shfb.codeplex.com/) is pretty cool). However, I thoroughly hate having XML documentation inline with code. I'd almost prefer an indent mechanism with some keywords that are equivalent to the XML comments -- so that I can keep the python-like paradigm even for that. But then that has most of the same issues that handling multiline strings has.

[Charles]

I agree that I don't want XML in the doc strings. Bleck.

The Java guys use a @foo approach. See http://www.google.com/search?hl=en&q=java+doc+comments

I've been using a leading dot on member names like "Blah blah .foo blah blah".