This automatically generates documentation from goal_src docstrings,
think doxygen/java-docs/rust docs/etc. It mostly supports everything
already, but here are the following things that aren't yet complete:
- file descriptions
- high-level documentation to go along with this (think pure markdown
docs describing overall systems that would be co-located in goal_src for
organizational purposes)
- enums
- states
- std-lib functions (all have empty strings right now for docs anyway)
The job of the new `gen-docs` function is solely to generate a bunch of
JSON data which should give you everything you need to generate some
decent documentation (outputting markdown/html/pdf/etc). It is not it's
responsibility to do that nice formatting -- this is by design to
intentionally delegate that responsibility elsewhere. Side-note, this is
about 12-15MB of minified json for jak 2 so far :)
In our normal "goal_src has changed" action -- we will generate this
data, and the website can download it -- use the information to generate
the documentation at build time -- and it will be included in the site.
Likewise, if we wanted to include docs along with releases for offline
viewing, we could do so in a similar fashion (just write a formatting
script to generate said documentation).
Lastly this work somewhat paves the way for doing more interesting
things in the LSP like:
- whats the docstring for this symbol?
- autocompleting function arguments
- type checking function arguments
- where is this symbol defined?
- etc
Fixes#2215
Favors the `lg` namespace over `fmt` directly, as this will output the
logs to a file / has log levels.
I also made assertion errors go to a file, this unfortunately means
importing `lg` and hence `fmt` which was attempted to be avoided before.
But I'm not sure how else to do this aspect without re-inventing the
file logging.
We have a lot of commented out prints as well that we should probably
cleanup at some point / switch them to trace level and default to `info`
level.
I noticed the pattern of disabling debug logs behind some boolean,
something to consider cleaning up in the future -- if our logs were more
structured (knowing where they are coming from) then a lot this
boilerplate could be eliminated.
Closes#1358
* decomp: add `docstring` support to relevant places in `all-types`
* decomp: output method docstring into the `defmethod` instead
* goalc: handle docstrings in `define[-extern]` (gracefully ignore for now)
* decomp: output docstrings for bitfield deftypes too
* goalc: fix `defenum` parsing when coming from the compiler (no symbol metadata to store to)
* lsp/tests: fix ups
* lint: formatting
* goalc: handle edge-case of defining a string constant
* cleanup leftovers, fix codacy issues, rename struct
* [goalc] macro expansion in integer constants
* working
* didn't break it yet
* support conditional compilation
* fix up some more small bugs
* fix duplicate evaluation of bitfield definitions
* paranoid
* begin work
* work
* working objs
* exporting
* it works
* before some time of day fixes
* add time of day interp and also fix zbuffer
* some small blending fixes
* improve randomess
* clean up extraction and missing blend mode
* culling, time of day, more level fixes
* more cleanup
* cleanup memory usage
* windows fix
* `flying-lurker`
* why'd this get left behind?
* also `ambient` and add a `banned_objects` config and fix offline tests
* clang
* fix `ambient-type-sound`
* support setting and accessing fields of a 128-bit bitfield
* remove print
* rework static constants
* support 128-bit bitfields as part of static structures
* dynamic construction
- Recognize new type definitions/parents/type flags in the decompiler
- Analyze autogenerated inspect methods and dump guesses at fields to a file
- Utility functions for accessing static data by label
- Better ordering in the decompiler to go through functions in the order they appeared in the source
- Added a decent number of types to `all-types.gc` based on the new field analyzer
- Correct a few `int`/`integer` mistakes in `gcommon.gc` (this should really be a warning)
- Correct a few type issues in `gcommon` and `gkernel-h`
- Option in the decompiler to be strict about `define-extern` redefining a type of a symbol
- Add a test to check consistency in types between `all-types.gc` (used by decompiler) and `goal_src` (used by the compiler)
* add some type stuff for gkernel
* more tweaks
* blah
* more little tweaks and more of gkernel
* add static structures with integer fields but not basics
* static structures
* update gkernel
* start cleanup
* fix typos
* fix syntax highlighting in doc
* lots of documentation updates
* clean and add tests
* more documentation and more error messages
* more document and try building kernel differently
* started adding simple functions in gcommon
* more tests and features
* more tests, debug windows
* debug prints for windows
* back up some regs for windows
* remove debugging prints
Mostly revolved around the new MSVC check for functions that don't cover all paths (ie. a switch statement without a default case). It appears to not see an assert as a valid default case.
I switched assert(false) to exceptions in these cases. I believe this should also abort the program, but will also provide a hopefully useful message? Hopefully this is an improvement.
Resolves#32
* add some more tests for let
* support static strings
* add function calling
* add prints for windows debgu
* one test only
* try swapping r14 and r15 in windows
* swap back
* disable defun for now
* fix massive bug
* fix formatting