[Snippet] SharedList

[Nestharus]

This resource has moved here.

--

gone

 

[Bribe]

*       Description
*       -------------------------
*
*           NA

It's no mystery why I haven't modded in so long.

 

[Magtheridon96]

One statement would be helpful, I mean, "SharedList" could mean many things:

• Shared ownership of nodes
• Allocation is done in a shared index space
• whatever...

List is explanatory enough, but the Shared part should be explained (briefly is good enough).

 

[Nestharus]

There's a key in the collection index

http://www.hiveworkshop.com/forums/jass-resources-412/collections-index-239205/

 

[Anachron]

How is this documented enough to get approved? It's just a copy and paste of the methods being inside.

You know, even though we are coders, some of us actually likes to read sentences that explain what the code does.

 

[Nestharus]

The method names themselves explain what the stuff does ;\

For example, push is a standard operation, the description would just be "push" lol

 

[Anachron]

In how many projects do you code professionally? Means get money for it.
Yes this is for fun but on one hand you create a "standard" and on the other hand your docs need a lot of work.

For any project, may it be a small omne like Dummy or big one like CustomInventory its better if you write big docs.

 

[Magtheridon96]

Not Big docs, just docs that aren't superfluous everywhere and can be read in no more than 2-3 minutes :/

Look at the Boost documentation for instance.

 

[Nestharus]

In how many projects do you code professionally? Means get money for it.
Yes this is for fun but on one hand you create a "standard" and on the other hand your docs need a lot of work.

For any project, may it be a small omne like Dummy or big one like CustomInventory its better if you write big docs.

Big docs make it hard to find anything. For me, I prefer a nice clean and quick API with minimal descriptions. If a description isn't needed, I leave it out =). Any descriptions about what the library specifically does go into the thread usually, that way the API stays as clean as possible. Only when the behavior is completely unknown, like some arbitrary function, will I write a full description. I'll also write descriptions for quirks. However, if there is nothing unknown and the method names follow clear standard operations, then I'm not going to write a description ; ).


The Shared is in the collections key, and as it's there and is a new definition for collections for wc3, I don't write it into the description of the resources themselves. Why? Too much information is a bad thing ; ).


Also, the code I write professionally for c++ is very different. The API is more organized than this, meaning that I can write in as many descriptions as I possibly can. I also like to do a nice organizing listing in the header files.


Now what might be worth doing is giving a link to the Collections Index if people are just going for the thread. From here, people can see the key and know what Shared means .

 

[Anachron]

Nes', I don't approve your way of documentation.
First you tell users "Code just needs a small API, the main docs should be somewhere else".
And now you tell me you separate this online submission and the real docs again?

So, if someone gets a map with your scripts, here is his todo:
Check you library, google for it to see the docs.
He will find the original map thread and visit it.
He will freak out because there is just another link to a short post.

I don't think this is a good pattern to follow...

 

[Nestharus]

no, I didn't say that at all >.>

The Shared thing is a new classification for wc3 that I came up with, and I don't document classifications, I define them somewhere and then use them.

As for the methods/fields, those are all self explanatory.

edit
I'm also following the stuff I laid out for standard 4 (although that stuff's still up for debate, it's not adopted yet)

API must be listed with details of all structs/routines/arguments/returns/fields that aren't obvious

Resource must be described if not obvious

Examples must be included within the API showing the usage of everything within the API that isn't obvious (iterating over a list, etc)

I guess the question here is, what's obvious and what isn't? : P


I don't see what I'm doing wrong here


Shared isn't obvious yes, but that's a new classification, so I defined it elsewhere as such. If you don't know what a stack is, you don't expect a Stack resource to define Stack for you, you look it up. Same goes with Shared ;\. Big principles like that I don't document in the resource.

 

[looking_for_help]

I guess everybody would be happy if you just add three sentences to the description, which clearly explain what the resource does and when and why you should use it.

I mean, "NA" is not an appropriate description, then you can leave that subchapter out anyway. The key "The Collection And Nodes Share The Same Recycler", well. If I only know whats a standard List, that wont help me that much. Google doesn't really help here neither.

I think a description should at least include a short summary of the resource, what makes it special and a simple (minimal) example of usage. That wouldn't make the the documentation big and people get an idea why they should use a Shared List and not a standard List.