Bogus identifier with colons in doc repository

[wasamasa]

I'm currently writing chicken-doc.el and walk over all installed eggs at some point. The sqlite3pth one raises a peculiar error when you try to fetch its data, either by chicken-doc :sql-result (note the missing trailing colon, unlike what the docs suggest) and this code snippet:

(node-children (lookup-node '(sqlite3pth)))

This occurs with both CHICKEN 5.1.0 and 5.2.0 and version 0.6.1 of the egg. See http://wiki.call-cc.org/eggref/5/sqlite3pth#api for the egg in question. While it's unusual the egg defines a :sql-result: identifier (note the trailing colon), it's definitely incorrect to omit the trailing colon in the chicken-doc database.

edit: This can be fixed by adjusting the identifier inside id.idx and root/sqlite3pth/,defs which suggests something went wrong while generating the documentation tarball.

edit: This might be the fault of svnwiki-signature->identifier in the svnwiki-sxml egg, it shows an example reminiscent of Ivan Raikov's eggs.

[ursetto]

I had a nice long writeup here, about how :sql-result: is actually the keyword #::sql-result, how it should properly be |:sql-result:| in the docs, how keyword identifier parsing behavior is considered undefined in chicken-doc, and how we could consider approaching this.

Then I deleted it, because I looked more carefully and realized the documentation is completely broken. Do these look like valid chicken-doc procedure signatures?

(:sql-result: string --> (or false fixnum)) 

(: sqlite3-prepare ((struct <sqlite3-database>) string --> (struct <sqlite3-statement>))) 

No, they are Chicken 5 type signatures, and chicken-doc cannot parse those. A documentation writer has to make at least a minimum attempt to respect convention.

chicken-doc should possibly be extended to support type signatures, but it would be with a new generic tag like signature or types. If you're interested in that, please open a new issue.

[wasamasa]

Thanks, I didn't notice the -> and --> syntax at all. I've compared the documentation page with the source code of the egg and found that the signature triggering this error is incorrect, it should be (: sql-index (:sql-result: string --> (or false fixnum))) instead. I've adjusted the wiki page accordingly, let's see whether that resolves the issue.

[ursetto]

It may prevent it from crashing, but the sig is still wrong; the identifier is a bare : and it will probably fall back to using a string (as in read syntax). See https://api.call-cc.org/5/doc/sqlite3pth. The doc needs to be fixed to not use type signatures, or ignore the doc.