Improve Embedding of Example Mod

[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

[cputnam-a11y]

Please note that this repository is for the fabric docs. To my best knowledge, discussion about the fabric wiki occurs on the fabric discord server in #wiki

[keetsta]

Please note that this repository is for the fabric docs. To my best knowledge, discussion about the fabric wiki occurs on the fabric discord server in #wiki

i am discussing fabric docs and referencing the fabric wiki because a lot of things are written better in wiki
all the problems i mentioned are the problems of this docs page

[cputnam-a11y]

Okay. It really seemed like you were discussing the wiki. Are you following the 1.21.2,3 and 4 update pr #242? At the current moment the wiki only follows <1.21.1 scratch that, I see you are. Good luck with the improvements:)

[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.

[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