1
0
mirror of https://github.com/SquidDev-CC/CC-Tweaked synced 2024-12-13 03:30:29 +00:00
Commit Graph

13 Commits

Author SHA1 Message Date
SquidDev
a6a1b9b8e5
Add a whole tonne of documentation
There's a bit of duplication here, so we might try to clean this up, but
it's a good starting point.
2020-07-09 21:59:19 +01:00
SquidDev
9f8774960f Generate documentation stubs from Javadocs
illuaminate does not handle Java files, for obvious reasons. In order to
get around that, we have a series of stub files within /doc/stub which
mirrored the Java ones. While this works, it has a few problems:

 - The link to source code does not work - it just links to the stub
   file.
 - There's no guarantee that documentation remains consistent with the
   Java code. This change found several methods which were incorrectly
   documented beforehand.

We now replace this with a custom Java doclet[1], which extracts doc
comments from @LuaFunction annotated methods and generates stub-files
from them. These also contain a @source annotation, which allows us to
correctly link them back to the original Java code.

There's some issues with this which have yet to be fixed. However, I
don't think any of them are major blockers right now:

 - The custom doclet relies on Java 9 - I think it's /technically/
   possible to do this on Java 8, but the API is significantly uglier.
   This means that we need to run javadoc on a separate JVM.

   This is possible, and it works locally and on CI, but is definitely
   not a nice approach.

 - illuaminate now requires the doc stubs to be generated in order for
   the linter to pass, which does make running the linter locally much
   harder (especially given the above bullet point).

   We could notionally include the generated stubs (or at least a cut
   down version of them) in the repo, but I'm not 100% sure about that.

[1]: https://docs.oracle.com/javase/9/docs/api/jdk/javadoc/doclet/package-summary.html
2020-07-03 13:31:26 +01:00
SquidDev
36bb8b67c9 Clean up data-gathering code
- Refer to this as "data" rather than "metadata". I'm still not sure
   where the meta came from - blame OpenPeripheral I guess.
 - Likewise, use getItemDetail within inventory methods, rather than
   getItemMeta.
 - Refactor common data-getting code into one class. This means that
   turtle.getItemDetail, turtle.inspect and commands.getBlockInfo all
   use the same code.
 - turtle.getItemDetail now accepts a second "detailed" parameter which
   will include the full metadata (#471, #452).
 - Tags are now only included in the detailed list. This is a breaking
   change, however should only affect one version (1.89.x) and I'm not
   convinced that the previous behaviour was safe.
2020-06-30 12:35:39 +01:00
Jonathan Coates
9499654757
Add documentation for peripherals
No clue how we're going to do this for the dynamic peripheral system
if/when that ships, but this is a good first stage.

Like the Java APIs, this relies on stub files, so we can't link to the
implementation which is a bit of a shame. However, it's a good first
step.
2020-06-24 12:12:06 +01:00
SquidDev
161a5b4707 Document and test the redstone library
The tests may be a little agressive, but I wanted some sanity checks for
the 1.15 API rewrite.
2020-05-15 10:03:47 +01:00
Lupus590
05d7be0362
Improvements to the various file system programs (rm, mv, rename) (#440)
This enforces several sanity checks before actually attempting
the move, allowing us to produce friendlier error messages.
2020-05-12 11:32:48 +01:00
Jonathan Coates
5739285fc2
Finish off documentation for the commands API 2020-05-05 21:17:52 +01:00
Jonathan Coates
8fac68386e
Fix usages of global variables
- Lint references to unknown fields of modules, excluding the keys and
   colours modules. This caught several silly errors in our stub files,
   but nothing else.
 - Lint on using unknown globals. This highlighted a couple of really
   silly mistakes. Fixes #427.
 - Add documentation for fs.attributes, fs.getCapacity and pocket, as
   they were not defined before.

Co-authored-by: JackMacWindows <jackmacwindowslinux@gmail.com>
2020-04-28 09:42:34 +01:00
Jonathan Coates
7f57a977a1
Make the CF link https on tweaked.cc
It doesn't play nice on GH, but we need it on our actual website.
2020-04-22 14:48:42 +01:00
Jonathan Coates
2f42a4e85b
Add documentation for shell and multishell
Heh, one place we're more complete than cc.cc :p.
2020-04-22 14:39:39 +01:00
SquidDev
eead8b5755 A small amount of Lua documentation
I'd forgotten how tedious this was. I can't say any of these docs are
especially good, but it's something.
2020-04-18 21:42:59 +01:00
SquidDev
f9f94b8304 Rewrite our documentation index
We're going to flesh this out a lot in the future, but this'll have to
do for now.
2020-04-16 18:18:36 +01:00
Jonathan Coates
ef8da8054f
An initial stab at documentation generation (#360)
This adds documentation comments to many of CC's Lua APIs, and
a couple of the Java ones, through the use of stubs. We then
export these to HTML using illuaminate [1] and upload them to our
documentation site [2].

Uploads currently occur on pushes to master and any release/tag. The
site is entirely static - there is no way to switch between versions,
etc... but hopefully we can improve this in the future.

[1]: github.com/SquidDev/illuaminate/
[2]: https://tweaked.cc/
2020-04-10 10:27:53 +01:00