search

eclipse-archived / ceylon.formatter

A formatter for the Ceylon programming language, written in Ceylon.
Apache License 2.0
14 stars 11 forks source link

Documenting the formatting options #91

Closed tombentley closed 9 years ago

tombentley commented 9 years ago

I'm not really sure that the documentation on the options being in the herd API doc is sufficiently accessible for people needing that doc.

So it would be nice if there was a way for the formatter to tell you what options it supported. Like running "ceylon format --optionhelp" would print detailed doc about the formatting options.

lucaswerkmeister commented 9 years ago

Perhaps --help=options, and we could add other help topics as well later?

tombentley commented 9 years ago

Well, you might find the ceylon tool "steals" that and doesn't let you get a look in.

lucaswerkmeister commented 9 years ago

Actually, it seems to only steal --help:

void run() {
    print(process.arguments);
}

$ ceylon compile tmp; ceylon run tmp --help=foo Note: Created module tmp/1.1.0 [--help=foo]

lucaswerkmeister commented 9 years ago

Blocked by ceylon/ceylon.language#566 – the output is long enough without printing every option twice :)

lucaswerkmeister commented 9 years ago

Blocked

Actually, if I don’t work around it, I’ll have to wait with ceylon.formatter 1.1.1 / 1.1.5 until Ceylon 1.1.5 is released… perhaps I’ll work around it.

lucaswerkmeister commented 9 years ago

--help=option:indentMode might also be useful to print help for only one option.

lucaswerkmeister commented 9 years ago

This is the output of --help=options: https://gist.github.com/lucaswerkmeister/9cb5caf071c2077a7a22

@tombentley is that okay?

tombentley commented 9 years ago

@lucaswerkmeister that's good yes. I wonder how much more effort it would be to produce full markdown output though, because you're using the DocAnnotation after all, AFAICS you wouldn't need much more than to put #### before the option name line, and to quote surround the name and the type with backticks, or something along those lines. If it's not easy then don't sweat about it.

lucaswerkmeister commented 9 years ago

It would probably be pretty easy… but I don’t know if it would be better. I didn’t intend for this to be markdown – in my opinion, it’s just meant to be printed on the terminal. If you want something prettier, get the ceylondoc already :)

lucaswerkmeister commented 9 years ago

Closing this issue for now, if anyone’s unhappy with the current output please open a new issue.