Preserve documentation and comments

[Tatsh]

Currently no comments are preserved.

This is the input:

/** UUID or string. */
type UUIDOrString = UUID | string;

interface Obj {
  /** The object ID. */
  id: string;
  /**
   * A longer description.
   * Part 2.
   * Part 3.
   */
  name: string; // A comment here.
}

Expected output:

UUIDOrString = UUID | str;
"""UUID or string."""

class Obj(TypedDict):
    id: str
    """The object ID."""
    name: str  # A comment here.
    """
    A longer description.
    Part 2.
    Part 3.
    """

An option like --no-comments could exist to ignore comments but keep docblocks, as well as --no-docs. Another option would be to output the alternative field description syntax (#: above the field) but currently VS Code's Python extension does not support this.

[jecki]

As of Version 0.7.5 multiline(!) comments can be preserved with the "--comments"-option. (There was unfortunately a bug in earlier versions that could cause invalid Python-code in some cases. Workaround: Eliminate all comments first.)

I'll think about the other options:

#: should be easy to implement. Does this mean that #: should be put in every line of a multilone doc-string or only the first?

docstrings are bit more complicated, because the comment needs to be moved to another place, but i'd consider this the preferred option.

[Tatsh]

Great progress!

#: should be easy to implement. Does this mean that #: should be put in every line of a multilone doc-string or only the first?

This one would be very low priority and definitely not a default. Basically this is something 'non-standard' maybe invented by Sphinx for those coming from languages where the documentation is always above the declaration (like Java, PHP, etc):

#: Pie.
#: Line 2.
PI = 3.14

As far as I know, if the line exceeds your max line length, you can break it but every line must start with #:.

I moved away from using the above syntax a long time ago. It is inconsistent when everything else in Python has the documentation coming after the declaration.