zig
zig copied to clipboard
ziglang
autodoc follow-up enhancements and bug fixes
Extracted from #19208.
- [ ] make the panic handler reflect the failure in the user interface
- [ ] when navigating back to search results, up+down arrow should keep working
- [ ] redundant search results (search "format")
- [ ] in query_exec_fallible, sorting should also check the local namespace inside the file
- [ ] walk assign_destructure not implemented yet
- [ ] escape URLs when rendering html (look for missing_feature_url_escape)
- [ ] implement renderHome for multiple modules
- [ ] struct fields: render each component separate rather than via source rendering
- [ ] infer comptime_int constants (example: members of #std.time)
- [ ] when global const has a type of type, categorize it as a type despite its value
- [ ] show abbreviated doc comments in types and namespaces listings
- [ ] show type function names as e.g. ArrayList(T)
- [ ] enum fields should not be linkified (example: std.log.Level)
- [ ] shrink Ast to fit the slices
- [ ] linkification of methods (example: std.array_hash_map.ArrayHashMap.count)
- [ ] navigating to source from a decl should scroll to the decl
- [ ] in source view, make
@imports into links, but keep same syntax highlighting - [ ] include struct field names and doc comments in search query matching
- [ ] include function parameter names and doc comments in search query matching
- [ ] instead of logging "can't index foo because it has syntax errors" put it in the UI
- [ ] in Walk.expr() it is missing support for asm_input/asm_output nodes
- [ ] in renderNamespace, handle an aliasing loop
- [ ] add a history item when clicking a search result (it already works when keyboard triggered)
- [ ] instead of "declaration not found", show the decl that can't be penetrated (example: #std.os.system.fd_t)
- [x] #19293
functions with parameters on multiple lines are rendered weirdly
should either trim the whitespace or render on multiple lines here as well
when navigating through search results beyond the page with arrows keys the page should be scrolled down or up before the selected result goes out of view
Should we also remove the "Parameters" headers?
Parameter-specific documentation is disallowed by zig fmt'd code, so the only information that we show is going to be present right above.
Parameter-specific documentation is disallowed by zig fmt'd code
im not sure what you mean? doc comments on parameters is certainly allowed. see this code for example
did you run into https://github.com/ziglang/zig/issues/18088 maybe?
With all this activity, maybe it is a good time for me to overcome my shyness and point to an alternative layout for the UI that I did some year ago whilst learning zig.
https://github.com/alwinb/zig-autodoc-ui
Live version here:
https://alwinb.github.io/zig-autodoc-ui/
I'm sure it would be easy to adapt the css for the new version.
Otherwise maybe it can serve as a bit of inspiration.
Public fields and functions inside of struct inside of test shown in docs but they shouldn't.
https://ziglang.org/documentation/master/std/#std.meta
I think it would be useful to be able to also generate documentation which doesn't include binary files (main.wasm and sources.tar) if possible. This should help reduce the repository size when managing the documentation using Git. Otherwise, I think the current situation is better because the generated document size is smaller.
additionally wrt sources.tar it would be nice if packages could define an external url where the source is located and the site would link to that instead of using the builtin source view.
One, probably easy to fix issue, that keeps coming up for me is that when I start typing into the search bar too quickly, it deletes my search input once it has finished loading.
https://github.com/user-attachments/assets/100dfc2b-c74d-45aa-97b6-8df3a8955194
Could you please open a new issue for it?
Sure thing, https://github.com/ziglang/zig/issues/21458.