fix: some comments

[line-o]

Normalize indent on multi-line comments and fill trailing one-line comments.

[DrRataplan]

I think prettier has some tooling for this that also handles tabs vs spaces. Called align or something

[DrRataplan]

Looking at this again, I am thinking two things:

100% for reformating and aligning docblocks. Since this is an opinionated formatter we should align with xqdoc. So docblocks shaped like this:

(:~
 : My comment
 :)

For normal block comments like you'd use when commenting out something, we should output it directly:

let $x := "bla"
(: let $_ :=
  util:log(
    "INFO",
    "The value for $x at this point is " ||
      $x ||
      " some more code to go over the 80 character limit"
  ) :)
return $x

As opposed to aligning all this to the start:

let $x := "bla"
(: let $_ :=
    util:log(
    "INFO",
    "The value for $x at this point is " ||
    $x ||
    " some more code to go over the 80 character limit"
    ) :)
  return $x

[line-o]

Yep, that sounds much better.
the colon alignment is already done in this PR but it will break the verbatim output.
What to do in mixed cases?

(:~
 : It started as a XQDoc 

but then I lost interest
:)

[DrRataplan]

playground

/*
Block comment
   AA
end
*/

/*
 * Not really anything...
 * But still indented
 */

/**
 * A full JSDoc
 * All the lines
 */

/**
 * It started as a JSDoc
But then I stopped caring
* And then I cared again!
    * A markdown list?
      * With nesting?
 */

[line-o]

Might be needed https://prettier.io/docs/plugins#utility-functions

[line-o]

oops ... let me remove the other PR first

[github-actions]

Visit the preview URL for this PR (updated for commit f1ff76f):

https://prettier-plugin-xquery-demo--pr7-fix-some-comments-bj8pklhz.web.app

_{(expires Sat, 31 May 2025 09:08:23 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 05f844b4fde774e8f22615c0409beb01474e9378}

[DrRataplan]

Let's do the following:

• For single-line comments ((: I am single line :) ), ensure leading space and trailing space for the content.
  • Do:
    • (: I am single line :)
  • Do not:
    • (:Too Close!:)
• For multi-line comments without leading : for all the lines of the content, ensure leading and trailing space for the content but trim spaces on the end of the line.
  • Do:

let $x := "a" 
(: let $_ := $x || "B"
let $_ := util:log("info", "The value of X is " || $x) :)
return $x

• Don't:

let $x := "a" 
(: let $_ := $x || "B"<space><space><space>
let $_ := util:log("info", "The value of X is " || $x) :)
return $x

• For block comments, if all the lines start with a :, align the : with spaces (<space>:<space>) and start and end with a newline. Finally, trim trailing spaces from all lines.
  • Do:

(:
 : I am multiline blocky comment
 :)

• Do not:

* (: I am multiline blocky comment
 : But I should not start with a newline
 :)

let $x := "A" (: I am multiline blocky comment
 : But I should not start with a newline
 :)
return $x

(:~
:I am multiline blocky comment
:But I am too cramped because my lines do not start with `<space>:<space>`
:)

(:~
: I am multiline blocky comment
: But I end without a trailing newline :)

(:~<space><space><space>
: I am multiline blocky comment<space><space>
: But I have trailing spaces<space>
:)

• For docblock comments (aka xqdoc) that start with a ~, enforce leading aligned <space>:<space> for all lines and start and end with a newline. Finally, trim trailing spaces from all lines.
  • Do:

(:~
 : I am a docblock
 :)

• Do not:

(:~ I am a docblock
: But I should not start with a newline
:)

(:~
  I am a docblock
: But I do not always start with a `:`
:)

(:~
: I am a docblock
: But I end without a trailing newline :)

(:~
:I am a docblock
:But I am too cramped because my lines do not start with `<space>:<space>`
:)

I would personally implement this is in a separate file to make unit testing it easier and prevent the main.ts from filling up too much. It's starting to become a set of relatively complicated rules.

[bwbohl]

First, many thanks for this great tool @DrRataplan. It still has some way to go, but it’s the best option I've found so far for good XQuery formatting. I tested this PR on some of my XQueries and was quite pleased with how it handled inline documentation comments. What I discovered, though, is that it sometimes adds extra space before a comment starting on a newline and which had no indentation before, both for some arbitrary comments and XqDoc comments.

[DrRataplan]

Hey @bwbohl,

Thank you for the kind words! Agreed, not done yet!

Do you have a clear example of where it does this? I would love to fix it, or at least make sure it's fixed as part of this PR! Could you open an issue for it?

Kind regards,

Martin

[bwbohl]

Do you have a clear example of where it does this? I would love to fix it, or at least make sure it's fixed as part of this PR! Could you open an issue for it?

I tried formatting the XQLs in https://github.com/Edirom/Edirom-Online-Backend/tree/develop/data/xql

For XQdoc comments, it seems to happen if they are preceded by comments or comments and empty lines, e.g.:

https://github.com/Edirom/Edirom-Online-Backend/blob/2048f74a76dd2f978e6490837899062d7bd01a0d/data/xql/getAnnotationInfos.xql#L33-L36

[bwbohl]

A good test candidate for handling inline documentation would be:
https://github.com/Edirom/Edirom-Online-Backend/blob/2048f74a76dd2f978e6490837899062d7bd01a0d/data/xql/getLinkTarget.xql#L154-L214

[bwbohl]

Oh, this one is good, because it has both cases with added extra space before the comment:
https://github.com/Edirom/Edirom-Online-Backend/blob/2048f74a76dd2f978e6490837899062d7bd01a0d/data/xql/getEditions.xql

line 6 and line 12