Use "common" format to generate comments file
GuillaumeGomez opened this issue · comments
For now, this is a custom format. Very useful and short, but maybe another one could fit this just as good.
At the very least § as a separator is problematic because the US keyboard layout doesn't have it.
That's the main goal. :p
Here's a relatively conservative idea: stick with markdown.
Rust docs are in markdown. Someone might want to edit them in a markdown editor if there exists such a thing.
-
Change the extensions to
md. -
Remove any
//!,///,/*!,/**and indentation. I believe managing the indentation can be automated. -
Modify the metadata format slightly to make it more compatible with markdown:
Example:
=! ./src/auto/gl_area.rs =/ //! A widget for custom drawing with OpenGL =| impl GLArea§fn new /// Creates a new GLArea widget.- Put the metadata in comments
<!-- =! ./src/auto/gl_area.rs --> A widget for custom drawing with OpenGL <!-- =| impl GLArea§fn new --> Creates a new GLArea widget.
- or in headings
# =! ./src/auto/gl_area.rs A widget for custom drawing with OpenGL # =| impl GLArea§fn new Creates a new GLArea widget.
- something else?
It wouldn't change this much. And I don't want to indent myself. If the person is using a super-wonderful-indent-of-the-death, well, then I have to put it back like it should be.
However, I was thinking of writing a software to edit this file more easily and to compress the data (so not readable anymore).
It seems you oppose the goal of making the cmts files easy to read and edit.
To be precise: adding a compress option. Not compressing by default.
What problem is that going to solve?
The file size (an excellent example is the generated gtk file). Otherwise none.
Sorry I don't see what's wrong with the size.
It doesn't matter for the moment. It's just something I'd like to add in the future.
Otherwise, I don't mind changing the format to markdown, but since I want to keep the indent untouched, it'll just be very ugly...
About that.
If the person is using a super-wonderful-indent-of-the-death
I'm not sure I understand who that person is going to be. I'm considering this tool in the context of the gtk bindings, where formatting is expected to be simple and consistent.
Fair enough point... Then let's get rid of the indent and convert all this to markdown.
I believe we can even get rid of custom "meaningful characters" and change from
=! auto/about_dialog.rs
=| struct AboutDialog
/// The `AboutDialog` offers a simple way to display information about...
=| impl AboutDialog§fn new
/// Creates a new `AboutDialog`.
to
<!-- file auto/about_dialog.rs -->
<!-- struct AboutDialog -->
The `AboutDialog` offers a simple way to display information about...
<!-- impl AboutDialog::fn new -->
Creates a new `AboutDialog`.
solving #12 at the same time.
But then, we're not in markdown. Do you want just metadata then comments?
The comments themselves are markdown and the metadata is tucked away in <!-- --> so it doesn't get in the way if someone uses a markdown-aware editor.
Okay, let's just hope balises like this aren't used in comments.