search

HaxeFoundation / haxe-evolution

Repository for maintaining proposal for changes to the Haxe programming language
111 stars 58 forks source link

Carry comments through to target language (through AST) #65

Closed TomByrne closed 4 years ago

TomByrne commented 5 years ago

A more comprehensive representation of code comments in Haxe AST would make for much more readable output and facilitate people using Haxe as a source-to-source tool.

Using a compiler flag, comments could be included in the generated code (e.g. -Dcomments) .

This would replace the doc property that currently exists on BaseType, ClassField & Field.

Rendered doc

Simn commented 4 years ago

I recommend splitting up this proposal into two parts:

  1. Retain documentation comments on types and fields.
  2. Retain in-code comments.

The reason is that 1. is several orders of magnitude easier to support. In most generators, it should come down to emitting an additional print at the right places (although determining these places might be a bit finicky).

I think we are unlikely to accept the second part because the benefit/complexity ratio is dubious.

TomByrne commented 4 years ago

Sounds good. If you don't think it'll ever be accepted, I'll just remove the section regarding comments in-code. Any thoughts on enhancing the parsing of comments?

RealyUniqueName commented 4 years ago

I think Haxe should handle asterisks correctly in docblocks. If the first non-space char on all lines is asterisk, treat it as the beginning of a doc line. Otherwise trim the shortest indentation level on each line.

kLabz commented 4 years ago

What about markdown lists? I wouldn't want them to be broken by this (and yes, my codebase would break with this).

I'm really not sure Haxe compiler should do anything with the content of the comments, and let macros/whatever parse them any way they want in userland.

RealyUniqueName commented 4 years ago

What about markdown lists?

If the first non-space char on ALL lines is asterisk

Do you have non-java-style docblocks, which have markdown list as their only content? IDEA and vscode both automatically insert java-style docblocks upon typing /**. Also, I think the style of docblocks from Haxe's std lib is quite unique among C-like languages.

Simn commented 4 years ago

We will implement support for retaining type and field comments in the output, see linked Haxe issue.

I'll close this PR because the actual proposal is a bit wider. It's unclear if in-code comments are feasible, but this can be discussed at a later point.