jasraj/q-doc

Javadoc inspired documentation generator for kdb+

q-doc's Issues

system d command

I find that parsing fails entirely when the system "l" command is present, i.e. the first one fails whereas the second one works

$ cat test.q
system "d";
/ print hello world
.test.f:{show "hello world";};

$ cat test.q
/system "d";
/ print hello world
.test.f:{show "hello world";};

This is an issue since a) not using system "d" to go into a context means you have to qualify every function name (which I don't actually mind so much, it's a bit tedious but it's more explicit so has its own advantages) but b) you may not always have control over loaded libraries.

In my case I am loading a q script which is external to me which makes use of the system "l" command. That fails my parser entirely.

Keen to add more comment tag support?

How keen are you to add more comment tag support, including some of the useful in-line tags?

I've completed the following addition in my own fork:

• @see external link support: / @see <a href="....">...</a>
• inline code block support: {@code ...} (including the <code>...</code> alias)
• inline literal block support: {@literal ...} (including the <tt>...</tt> alias)
• support for HTML contents in descriptions
• (non-javadoc) one-line k/q code support: / q) .... or / k)....

Please kindly let me know if you are interested these features as additional a pull request.

Support for mac

Hi Jas

We're having a look at this, looks good and a fit for what we need. I tried to do a PR for a small change to support macs, but was denied access. This is the change:

diff --git a/q-doc.q b/q-doc.q
index 884398d..f5306cb 100644
--- a/q-doc.q
+++ b/q-doc.q
@@ -50,7 +50,7 @@
:hsym first `$trim system "echo %cd%";
];

•   if["l"~first string .z.o;
  

•   if[(first string .z.o) in "lm";
            :hsym first `$trim system "pwd";
    ];
  

Would you be able to add that?

Thanks

Jonny

Backslash in one line function body

Thanks for the code, I find it very useful. I added an @example tag that parses an example function call.

I did realize however that the parser can have troubles with certain functions. One such case is backlashes in one line function bodies.

Example:
/ backslash in function falls over
/ @param input (String) list of strings
/ @returns (List) of strings, comma appended
f:{[input] : input ,:","};

/ same function, multiline, with backslash in between
/ @param input (String) list of strings
/ @returns (List) of strings, comma appended
h:{
[input] : input ,:","
};

h gets parsed correctly, f does not

Integrate with BuaBook kdb-common

Use https://github.com/BuaBook/kdb-common as the core of the application.

How to save the doc offline?

Hi Jasraj,

I have tried your q-doc on my Q codebase. It works great. But, my concern is that I want to save the documentation on disk and want to see the documentation on demand offline i.e. I don't want it to be running as a service. Is there a workaround to do it?
I am not very proficient in Javascript or JSON.

Thanks,
Shatrughan.

No Description Causes No Documentation to be Generated

If there is no function description all other supported q-doc syntax gets ignored. Add support to allow documentation where there is no function description.

A few feature requests...

Hi Jas

Ok so I'm not really asking you to do this - more asking advice if you think there would be any issues doing them, or if there is currently a way. If we do them we would hope to submit the changes back to the repo as PRs.

1. Extend support for dictionary arguments. You can declare an argument as a dict, but then it doesn’t give a way to specify what the keys are. Could probably do some custom html in the argument description, but it seems that has to all be on one line so the q file would become a bit unwieldy. Possibly a new tag type here?
2. Would be nice to be able to multiline the tag description in the q file.
3. You can’t stop it from documenting a function e.g. @ignore or something. Currently anything we want to expose in user documentation has to be a separate file without any internal functions (which may be good practice anyway). But it would be nice to be able to mark something to be ignored.
4. It expects the documentation block to be above the function declaration. Given changes in 3.6 it would probably be nice to have the documentation inside the declaration for our own ease of use.
5. A search function on the html pages would be great!

Thanks

Jonny

function with variable, if statement and show

Possibly a rather obscure edge case. The last function causes the parsing of the entire file to fail

/ return true if true is true, no params
/ works
g:{ if[1b=1b;:1b };

/ show true if true is true, no params
/ works
k:{if[1b=1b; show "true"]};

/ return true if true is true, params
/ works
l:{[]if[1b=1b;:1b]};

/ show true if true is true - this one fails the whole file
/ fails
/j:{[] if[1b=1b; show "true"]};

bug reports

if the backspace between the return type and description words is less than 2, the first description word will never show, as below,if the backspace between right bracket of returnType and the word "Return" is less than 2, the word "Return" will never show

Bug in funcAndArgs parser for single-line functions

A possible bugfix:

------------------------------- q-doc-parser.q --------------------------------
index 448f4c1..e4761d7 100644
@@ -132,8 +132,8 @@
     namespaces:fills?[namespaceSwitches;`$2_/:funcSignatures;`];
 
     / Recover namespace for each function
-    funcAndArgs:(!). flip(({$[(~).(first;last)@\:y;`;$[(null x)or(y[0]like ".*");::;` sv x,]`$y 0]}@/:namespaces),\:last)@\:'":"vs/:funcSignatures;
-    funcAndArgs:{ $[not "{["~2#x; :enlist`$"..."; :`$";" vs x where not any x in/:"{[]} "] } each funcAndArgs;
+    funcAndArgs:(!). flip(({$[(~).(first;last)@\:y;`;$[(null x)or(y[0]like ".*");::;` sv x,]`$y 0]}@/:namespaces),\:{":"sv 1_x})@\:'":"vs/:funcSignatures;
+    funcAndArgs:{ $[not "{["~2#x; :enlist`$"..."; :`$";" vs x where not any((count[x]^first x ss"]")#x)in/:"{[]} "] } each funcAndArgs;
 
     commentLines:{last[y]+(last[y]_x)?z}[file]\[0;funcSignatures];
     commentLines:commentLines - til each deltas commentLines;