Documentation Sprint #36
Conversation
|
I'm for this, I prefer verbose documentation inside the codebase vs. in a README at this stage as it encourages people to read the code itself and is easier to ensure remains up to date. |
|
I think the README needed at least a few words that aren't Julia code, so I've added them in commit 38ea219. There should also be paragraph at the top that answers the questions:
It should take about 6-8 sentences to get that across. I'm not sure how to word it or what to say, since I've been focusing on websockets and not anything bigger-picture. The three levels of possible interaction (Http, Micro, Meddle) should be mentioned/compared briefly. |
Blasphemy! |
|
I'm totally in favor of code and usage documentation. I'll try to find time this weekend to document the code I've worked on or with so far. @StefanKarpinski To my knowledge, Julia auto-generates some of its documentation, I assume from code comments; is there a way for us to use this? |
This is a good idea – we should all make this a priority as it will enable others to contribute much more easily. |
|
@zachallaun They have .rst files (separate from the code) to generate the web documentation and the database that the REPL's |
|
Ah, thanks for the explanation. I'd love to be able to generate Markdown from code comments. Anyone care to hack something together? |
|
So, are you thinking something that would (given a file of Julia code) take comments from directly above functions/types and the name/signature of the definition, and spit out Markdown? Or something else? |
|
A good example of this is docco.js, sounds like someone should write
|
|
We don't actually autogenerate any docs – it's all in the doc directory in ReStructuredText format, converted to HTML by Sphinx. |
|
It would be good to brainstrom about how Julia semi-literate and illiterate documentation should work. I haven't come to any conclusions although there's been some big discussions, such as this one: JuliaLang/julia#1619. |
|
I like the idea of |
|
I guess it's a bit different, but I know OCaml (and I think Haskell) has the concept of a documentation plugin. Basically, you run a tool developed with the compiler (ocamldoc for OCaml), and it will had your documentation plugin the various entities that are in the code (like modules, functions, types, etc). Your plugin can output whatever it wishes, which allows for html documentation of various forms, or even search engines (like Hoogle, which is awesome). Besides just parsing the code for you, ocamldoc decides which comments are attached to which modules/functions/etc. This means that the same rules for deciding this apply to all documentation plugins and that the plugins don't have to worry about it. It grabs comments from next to entities based on certain rules, so there's no special I like the flexibility that this plugin approach provides. Having a plugin makes it straightforward to take the same data (documentation/etc) and create completely different output. It might, for example, allow you to organize documentation for all installed packages by function instead of by package (so all the |
|
@StefanKarpinski is this what you mean by illiterate documentation? |
|
I really like the idea of the documentation plugin, and I also am used to seeing comments immediately above a function/entity. One upside of |
|
You would have to have the module/code loaded in order to get the (where parsing as a separate step means that all the (local?) code has docs available once you've built them, even if they haven't been imported yet) |
|
Yes, the code would need to be loaded for the macros to execute. I wonder if files can be dynamically loaded if fully-qualified names are queried? e.g. |
|
If it loads the module automatically, would it pollute your namespace or similar? or, I guess if it's qualified like that, do you assume that's what they meant to do? I think I'd like |
|
Something I think would be really neat to do, given a documentation plugin interface, would be to make a Hoogle-like thing for Julia. Mainly, I mean a search engine that can handle type signatures, not just string-based search of the docs. Rather than just the The type-base documentation search is one place where a documentation plugin interface beats a "just hand me strings, please" type thing. You need some kind of real type information in order to do the type stuff properly. |
- Moves GC method `clean!` from callback to below blocking loop in `process_client` - Adds explicit types to `WebsocketInterface` methods - Verbose documentation
Added examples for the route function and described the routing_tables function.
- Moves GC method `clean!` from callback to below blocking loop in `process_client` - Adds explicit types to `WebsocketInterface` methods - Verbose documentation
Groups cfunction calls together under Julia function definitions.
I haven't been paying much attention to the details of your webstack construction, and I realized last night (when I wanted to make it serve a specific file) that I didn't know what was going on.
I'm also not aware of any real documentation beyond uncommented examples.
I've added some comments to Meddle.jl that I think explain what these "middleware" things are/do. It is probable that I've misunderstood some of it, so please correct me.
I'm not sure this is the best place for this documentation, since annotated examples of using it is better. With sufficient annotation of our existing examples, a note in the README about how to actually run the examples might suffice as a tutorial.
This kind of documentation should really show up in the REPL in
help, but I'm not sure what we'd need to do to make that happen. (Can packages add to the help/documentation database that the local REPL uses? @StefanKarpinski)