Valadoc 0.23.2

This is a very convenient form for single line properties, so I have been looking into a fix. Here's an example, using valadoc rebuilt with DEBUG and DEBUG_HARD:

> rfc822.vala:9.4-9.10: error: expected <end-of-line>: Common
> * Common text formats supported by {@link Geary.RFC822}. 
>    ^^^^^^                                                 
> An error occured while parsing: expected <end-of-line>: Common
> 
> Dumping rule stack:
> 	 0: Comment        [seq]          (index=0/3)

The immediate problem seems to be the Comment rule in documentationparser.vala, which does indeed require an EOL up front:

>  		Rule comment =
> 			Rule.seq ({
> 				TokenType.EOL,
>  				Rule.option ({
>  					description
>  				}),
> ...

That can be changed to make the initial EOL optional:

> 		Rule comment =
> 			Rule.seq ({
> 				Rule.option ({
> 					TokenType.EOL,
> 				}),
> ...

But then the parser will complain about the EOF instead:

> rfc822.vala:9.59-9.59: error: unexpected token: <end-of-file>
> * Common text formats supported by {@link Geary.RFC822}. 
>                                                           
> An error occured while parsing: unexpected token: <end-of-file>
> 
> Dumping rule stack:
> 	 0: Comment        [seq]          (index=2/3)
> 	 1:                [option]       (started=true)
> 	 2: Description    [seq]          (index=1/2)
> 	 3: Blocks         [one-of]       (selected=5/6)
> 	 4: Paragraph      [seq]          (index=2/2)
> 	 5:                [many]         (started=true;done_one=true)
> 	 6:                [seq]          (index=1/2)
> 	 7: Run            [seq]          (index=3/3)
> 	 8:                [option]       (started=true)
> 	 9:                [many]         (started=true;done_one=true)
> 	10:                [one-of]       (selected=1/3)
> 	11:                [one-of]       (selected=0/2)
> 	12:                [seq]          (index=1/1)
> 	13: Text           [many]         (started=true;done_one=true)

Adding a further optional EOF to Comment (also tried Description and a few others), or getting a \n inserted on EOF seems to break parsing all comments, with the following:

> An error occured while parsing: Rule stack is not empty!

So I'm not sure where to go from here, any pointers?

CC'ing Florian and Didier for some advice, since they seem to have written most of that class.

Hi Nathan and Michael,
I don't have a computer at hand these days. I'll take a look at it on Monday evening or next week if you did not find a fix before.

Hey guys,

there is a similar issue at the end if I recall it correctly. I think the easiest solution is to build a new rule based on `run` and apply it to single-line documentation comments.

Created attachment 366525 [details] [review]
Add support for single line documentation comments

Patch adds support for single line comments, using Florian's suggestion to base a new rule off the Run rule.

It should be pretty safe to commit, since it only is triggered if the original form starting with a LF does not apply.

This fixes all instances of the issue in Geary's codebase.

commit 45792e40c2acb2f19e3124d2f41632f044c1158d
Author: Michael James Gratton <mike@vee.net>
Date:   Tue Jan 9 12:30:50 2018 +1100

    libvaladoc: Add support for single line documentation comments