Improve Reference Mod Awareness

[keetsta]

Docs page: https://docs.fabricmc.net/develop/items/first-item

referencing fabric wiki, there should be a context for some points

1 - downloaded texture name is not matching the texture mapping name in the tutorial which should be equal
2 - in the fuel section, there is no clarification about the register context, in fabric wiki there is an example with context provided. Also, this is a frequent problem occuring in some other articles like Custom Groups

public class ExampleMod implements ModInitializer {
    // An instance of our new item, where the maximum stack size is 16
 
    // For versions below 1.21.2:
    public static final CustomItem CUSTOM_ITEM = register("custom_item", new CustomItem(new Item.Settings().maxCount(16)));
    // For versions since 1.21.2:
    public static final Item CUSTOM_ITEM = register("custom_item", CustomItem::new, new Item.Settings().maxCount(16));
    [...]
}

there's a lot of moments like this but i assume that you are planning to rewrite it for newer versions

[IMB11]

Hi, thanks for making an issue, I'm not sure what you mean by "register context", do you mean an explanation on what the register method is? This is clarified at the start of the items docs page.

[keetsta]

Hi, thanks for making an issue, I'm not sure what you mean by "register context", do you mean an explanation on what the register method is? This is clarified at the start of the items docs page.

no, i mean explanation of where the function is called, because sometimes it is not very clear

[sbman]

There is other contextual information missing earlier in this same document. In the 'Preparing your Items Class', there is nothing showing where all the classes needed to actually implement the example code come from. A new user (like myself) has no idea where you import Item, Identifier, Registry, Registries, and that the 'FabricDocsReference' should reference your own 'new item' class.

The doc should note that your class must use these imports or show a full code example that includes the references, snippets of code aren't great in a tutorial. A link to a fabric/yarn class documentation would also be very helpful. I found one at: https://maven.fabricmc.net/docs/yarn-1.16.4+build.1/allclasses-noframe.html although I don't know if that is an official source or note.

The example code in the 'preparing your items class' should include these lines:
import net.minecraft.item.Item;
import net.minecraft.util.Identifier;
import net.minecraft.registry.Registry;
import net.minecraft.registry.Registries;

[its-miroma]

The doc should note that your class must use these imports

we expect Java developers to be at least a little familiar with some coding concepts, such as importing classes.

or show a full code example that includes the references, snippets of code aren't great in a tutorial.

we recently added a note in the starting page for developers with a link to the full reference mod.

A link to a fabric/yarn class documentation would also be very helpful.

you can find those from the official fabric website, albeit I'll admit that's not mentioned in the docs.

[sbman]

The doc should note that your class must use these imports

we expect Java developers to be at least a little familiar with some coding concepts, such as importing classes.

or show a full code example that includes the references, snippets of code aren't great in a tutorial.

we recently added a note in the starting page for developers with a link to the full reference mod.

A link to a fabric/yarn class documentation would also be very helpful.

you can find those from the official fabric website, albeit I'll admit that's not mentioned in the docs.

I'm a long time developer and expecting the reader to know to import classes is a safe assumption. However, if this is intended as a tutorial, this is a huge API with hundreds of classes. Where do you import them from? I jumped directly to the 'Getting Started' section, followed through all the setup and didn't see the link to the full reference mod, maybe some repetition of that link would be helpful. That said, I was able to find the class locations with some searching on my own and get the snippets built into a working project.

[IMB11]

I think it would be beneficial to automatically add a references section to the end of any developer pages that provides links to any transcluded code blocks.

Also see the discussion on Discord

[sbman]

I think it would be beneficial to automatically add a references section to the end of any developer pages that provides links to any transcluded code blocks.

Also see the discussion on Discord

It looks like the referenced code project doesn't match up with the tutorial anyways. It may be a completed mod, but none of the code shown in the tutorial is actually present in the referenced project making it of limited use to someone trying to figure things out for the first time. It is useful for attempting to extract reference locations and project structure, but not as a side-kick to the tutorial snippets.

[its-miroma]

could you elaborate on how that is? the docs (not the wiki!) literally embed code from the reference mod

[sbman]

could you elaborate on how that is? the docs (not the wiki!) literally embed code from the reference mod

Yes. the docs reference the 'sample mod' code on the docs page located at 'Developer Guides':
https://docs.fabricmc.net/develop

There are three versions of code located there and it looks like the 'latest' section contains the example code, but the project is further advanced from the 'Create your First Item' page. For instance, it references adding your translation to src/main/resources/assets//lang/en_us.json

If we go to that location in the sample at:
https://github.com/FabricMC/fabric-docs/tree/main/reference/latest/src/main/resources/assets/fabric-docs-reference

We can get down to the level, but there is no Lang folder and no translation json in this location. It must be somewhere else?

I was able to find ModItems.java in the location referenced by the documentation, but some of the other files aren't in the locations referenced in the docs.

Here are some more examples:
Docs tell you to put your model json in: assets//models/item
the github path: https://github.com/FabricMC/fabric-docs/tree/main/reference/latest/src/main/resources/assets/fabric-docs-reference/models
Does not contain item folder and therefore no model json.

Docs tell you to put your item model description json in: assets//items
assets//items
The github path: https://github.com/FabricMC/fabric-docs/tree/main/reference/latest/src/main/resources/assets/fabric-docs-reference
Does not contain an items folder, and the items model description json isn't there.

I'm sure these files are somewhere, and they probably get put into different places as the example becomes more complex, but that makes referencing the code as you work through the tutorial in the beginning stages fairly difficult. I'm sure once you have more time working with this particular object model and project structure, you know where these things live.

[cputnam-a11y]

Huh. That one file is the only one from that page not transcluded. I would have thought there would be a lint for inlining code

[IMB11]

All the assets are datagen'd to ensure that the JSON files can be easily updated if the format changes in future updates. You can find them in the src/main/generated folder, not src/main/resources.