jasraj
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.
- 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?
- Would be nice to be able to multiline the tag description in the q file.
- 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.
- 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.
- A search function on the html pages would be great!
Thanks
Jonny
Hi Jonny,
It's great that you'd like to extend q-doc - obviously I would appreciate any improvements or new features that you want to contribute back.
In summary I think they are all great suggestions :).
My thoughts on your feature requests:
-
Yes I think that would be good feature as it's something I've come up against myself. A new tag (
@param-keyor@dict-key) I think would definitely be the way to go on that. -
Yes the multi-line description for each tag would be good. The reason I didn't do that originally is that you have to look forward for the next tag (or the end of the comment) and I just didn't do it at the time.
-
I agree -
@ignorewould also be a good one (and quite easy to add I think). -
Yes I assume you mean so you can see the comments when you query the function via qPad or qStudio? If we specified strict rules (must be the first set of lines after the function definition, then it would work.
-
I think the HTML page should probably be entirely re-written. It was (deliberately) very basic but to add features such as search, a page with a newer JS framework would make this easier.
I couldn't give any guarantees if / when I could work through them, but if you would like to contribute back, I could create issues for each one and then could work against each one?
Sorry about slow response here, been working on some other stuff. I'll hopefully get a bit of time to look at this now. Can I create a branch to work on and then pull request it when done? I think you may have restricted branch creation.
Hi Jonny,
I've added you as a collaborator for now. You can also fork the repo, branch and pull request back as well if that's easier.
Looking forward to a PR!