Missing Router docs

[andyDoucette]

I'm new to Genie, and so far it looks like a great framework! One big obstacle to ramping up is that the API documentation isn't 100% complete yet. It seems to me like maybe 50% there. Here's an example:

I was going through an example that made a router and used a "route" function.

route("/packages/:package_id",
"packages#PackagesController.Website.show",
named = :package)

Curious what the heck is going on here, I wanted to look up the definition of the inputs to the route function. So I do some googling and end up here:

https://genieframework.github.io/Genie.jl/dev/API/router.html#Genie.Router.route

The only API documentation on Genie.Router.route seems to be this:

Genie.Router.route
—
Function
Named Genie routes constructors.

That's completely not helpful in telling me what the inputs are and how to use it.

There are many more examples. I can look at the source-code, but something is wrong if I have to do that.

Am I missing some documentation somewhere on the web that is complete? If not, I'm wondering if we can improve the documentation together? Since I'm just getting started, I don't have much knowledge of how things work, but for starters I could submit a pull request to add function signatures to each and every docstring. I would use DocStringExtensions.jl (and add it as a dependency to Genie) and use the $TYPEDSIGNATURES feature. Anywhere where the signature IS in the docstring but is not in the code, I would put it in the code and refer to the code as the single source of truth. This could possibly break some things, but only if the docstring and the code are somehow incompatible and then we should break it so we can rectify the discrepancy.

Would such a pull request to add function signatures to every docstring in Genie be accepted?

[essenciary]

Yes, agreed, documentation can be considerably improved.

The guides contain a lot of info (especially related to the router) but better doc comments would be very useful nonetheless: https://genieframework.github.io/Genie.jl/dev/search.html?q=route

The docs are actually a separate project so we don't need to add docs dependencies to Genie, they're handled here: https://github.com/GenieFramework/Genie.jl/tree/master/docs

DocStringExtensions would be a start though not necessarily the best use of your time. As you said, actual doc comments are needed, and that would have the greatest impact (eg documenting the various Router methods once you understand them).

Yes, any documentations PRs would be greatly appreciated and happily accepted :)

[andyDoucette]

Thanks for your support! I can add the function signatures. I plan to make a script to do it for me. Since function comments are meant to say how a function "should work" and that original intent is only know by the original author, me coming in and commenting someone else's code with what I think it does isn't nearly as helpful as that person coming in and writing what they intended for the code to do. When it's intent, then if the code doesn't match the intent then we know there's a bug. If someone documents a function based on what it does as opposed to what it's supposed to do, then the bugs get "baked in" to the intent. That's not good. So, in my opinion, the person who wrote the code is the only person who can accurately document it. But I'll try to do my little part here too by adding the function signatures at least. It'll be a good way to practice my fledgling Julia skills. ;)

[andyDoucette]

Oh, and yes, the documentation on the tutorial side is great! There's lots of examples available. Just the API docs needs some TLC. :) It's really a great project and I'm excited to contribute my $0.02 worth. ;)

[andyDoucette]

Oh wait... I do think we'll need to add DocStringExtensions to Genie because without that, people will get an error when julia tries to interpolate the $TYPEDSIGNATURES variable in the docstring. I guess we could put some sort of 'If this module is not available, set TYPEDSIGNATURES to ""' logic at the global level. But then, users who are getting the docstrings through their IDE or through julia's help system won't see any function signatures in the doc strings at all (because I'll be taking the exiting ones out so there aren't duplicates). So, I think in the end in order for my proposed suggestion to integrate well, DocStringExtensions will probably need to be a dependency of Genie. Are you ok with that?

[essenciary]

In this case it doesn't sound great. All dependencies are thoroughly vetted and I'm always trying to remove as many as possible to reduce precompilation time and lower the risk of versioning issues. All the documentation so far simply repeats the name of the function (a simple copy/paste), so if it's just for this, IMHO it's not worth the overhead.

[andyDoucette]

Yeah, I totally get that.  In something like a web framework it's important to know your code very well to make sure there aren't security vulnerabilities or bloat.  I think that little "If this module is not available, set TYPEDSIGNATURES to ""' logic can be added to take care of the situation and then we can just add the dependency to the docs repo. People can get their documentation online, which most of them probably do anyway. :)