Forge API Documentation

[biscuitWizard]

Hey there!

 

Sorry for asking this on my first post, but why is there no forge/FML API documentation? I've searched the forums and looked around on google for some sort of documentation, but have turned up nothing. It kind of seems like a glaring misnomer to me, especially when modders should have some kind of unified documentation when working with an API.

 

At the moment, the code I'm working on steps on the toes of ItemBucket, ChunkProviderGenerator, World, and numerous WorldGen* files, and I know for a fact that isn't going to bode well for compatibility with other mods. Worse yet, I know there /are/ forge hooks around in the code, I've seen them, but they're scattered and undocumented. I'm really not sure what to make of this.

 

Is there some kind of documentation? Or is there some way to learn to ropes without needing to read through all of the forge code?

[LexManos]

The code is documented, read the code.

It is not possible to generate good javadoc html because we are working with decompiled Minecraft code.

99% of the documentation generated by running javadocs over MC would be jibberish.

Your best is is to read the code inside the forge package.

 

If someone wants to take it upon themselves to go through the code and document it on our wiki, then they are more then welcome to.

I am not going to do it because I do not write good

[biscuitWizard]

I write lesserer good, but if I can decode the FML/Modloader/Forge API code, I'll write up some wiki docs.

 

Meanwhile, I suppose I will continue breaking this code.

[jjw123]

i MIGHT start a javadoc type thing on the wiki

[jjw123]

i know how daunting moving to forge is as a modder and now that i have done quite a bit with it id like to help people make that jump

 

EDIT: where would i put it? or can someone with permissions add Javadoc under the Advanced Tutorials link

[calclavia]

  On 6/20/2012 at 8:26 PM, jasonw749 said:

i know how daunting moving to forge is as a modder and now that i have done quite a bit with it id like to help people make that jump

 

EDIT: where would i put it? or can someone with permissions add Javadoc under the Advanced Tutorials link

 

I started modding with Forge included, so I never had to "move" to Forge. You should create a bunch of tutorials in the tutorial wiki from beginning on how to mod with Forge WITHOUT ModLoader. Your tutorials will get more views since it will be updated to the newest version of Forge which does not include ModLoader.

[jjw123]

i was gonna make a javadoc type thing that just explains methods

[jjw123]

where would be the best place to post it? under beginner tutorials? or should i wait for someone with permission to add javadoc to the list?

[calclavia]

  On 6/20/2012 at 9:04 PM, jasonw749 said:

where would be the best place to post it? under beginner tutorials? or should i wait for someone with permission to add javadoc to the list?

 

Beginners

[jjw123]

ok,

 

im gonna start it, people feel free to add to it at any time

[Geethebluesky]

Hey guys!

 

Are you open to edits for grammar, clarity and the like?

I'd be doing that while absorbing the contents.

 

(Perhaps this will make some people less shy about contributing. =)

[LexManos]

Not particular, unless its a single commit that sweeps everything.

My spelling isn't THAT bad, you can understand all of my comments.

I typically don't accept grammar nazi PRs, esp if its just comments.

[jjw123]

yeah, its on the wiki, anyone can edit anything

 

i have the first class done and would like feedback regarding layout

[jjw123]

ive done another class (im not avoiding the classes in between, i just havent used them yet, so im gonna do them after ive done the ones that ive used)

[jjw123]

i got the other classes in, people can fill in the information whenever, be sure to add your name to the authors at the bottom

 

im going to bed now but ill add some more tomorrow

[LexManos]

-.- Dont triple post -.-

[jjw123]

im sorry, i didnt realise

[Geethebluesky]

LexManos =/

 

First of all, I'm not a grammar nazi.

Second, I enjoy well-written English the same way you enjoy well-written code. My intent isn't to make people feel miserable about having their writing corrected. It's to have a clear message on the Web. (For once of all places)

 

It's nothing personal. I don't care who the heck makes the mistakes, just that the result is neat.

[Jarofdoom]

  On 6/20/2012 at 10:56 PM, Geethebluesky said:

Hey guys!

 

Are you open to edits for grammar, clarity and the like?

I'd be doing that while absorbing the contents.

 

(Perhaps this will make some people less shy about contributing. =)

 

Also a grammar fix PR gave a compile error in the past. It's a case of 'if it aint broke, dont fix it'

[Geethebluesky]

It's sad when people can't differentiate variable names from actual text designed to be read.

 

If people are that worried about it, *shrugs* Oh well. =)

[OvermindDL1]

I added a Documentation section, feel free to fill it up with a raw reference documentation.  No tutorials or so, just fill it like a raw reference guide:  http://minecraftforge.net/wiki/Tutorials/ForgeDocumentation

[alburdet619]

I know this is a really old thread but I want to say that I agree completely that there needs to be some sort of documentation.  C# coding is my job and I've produced and worked with many API's.  In any API, there is literally no way to know how to use it without documentation.  I mean sure, you can spend hours upon hours staring at each class but as it was stated earlier there is even stuff in the base minecraft classes like Item and Block that you don't see unless you know to look.  I am new to MC modding and I've been working at it for a couple of weeks now trying to cling to little bits of information I've gleamed from videos and tutorials that I've found here and other places but it isn't a substitute for real documentation.  I know it's a pain but it's also good coding practice.

 

My example of why:  I created several new ores and such and have added tools for each of them.  Well the only way I found before to add to the EnumToolMaterial was to create my own class that mimics the behavior of EnumToolMaterial and set my own values.  This of course means to make the sword I have to extend ItemSword, or ItemPickaxe for the pickaxe tools and so on.  If I had known about the EnumHelper class before I wouldn't have had to go through that pain.  Again though, I just saw this in the little bit of produced documentation and I haven't had a chance to look into it.  It may not even do what I think it does.  Who knows?

 

So please, don't think I'm saying you're doing a bad job in any way.  I think what you've provided here is invaluable for the modding community.  My message is just that producing an API should always mean producing documentation on using that API.  Do with that information what you will.

[LexManos]

1) Please don't necro YEAR old posts.

2) I am very bad at writing documentation. Tutorials, examples, etc..

Combine that with the fact that the Bulk of the code you're interacting with is decompiled Minecraft code. Nothing to do with Forge at all. Theres really no way I ca go through and document everything as 1) I don't know what some parts do exactly and 2) That would explode the patches so much for just documentation.

 

So, its up to the community. Make a nice place for resources to be posted. Those with the capability create good tutorials and point users in the right direction.

Almost everything that Forge adds directly is either documented fairly well, or self explanatory. But as I said i'm bad at it.

Yes I to have worked with many different APIs and codebases in my years of programming. On both sides of the spectrum, worse then we have and better then we have. I find that the best tool a programmer can have is his ability to understand code. Not his ability to read or write it, his ability to UNDERSTAND it. The mind that can consume the code and understand what its doing and how it's doing it. Being able to be your own documentation is good. Not an excuse for lacking documentation, but meh.