Advertisement:
2by2host
« previous next »
Pages: [1]   Go Down

Author Topic: Documenting what is in the code  (Read 2723 times)

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Documenting what is in the code
« on: August 09, 2012, 03:49:14 PM »
This evening I started a page on my wiki userspace (or whatever is called) where I'd like to collect things about SMF code:
http://wiki.simplemachines.org/smf/User:Emanuele/codedoc

I started with $user_info['mod_cache'] because I was trying to use it and I was not sure what (the heck) was in that array.

Eventually I'll move it to a proper wiki page, so if you want to contribute (both writing something or fixing errors) feel free to! ;D
« Last Edit: August 11, 2012, 04:36:36 AM by emanuele »
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #1 on: August 11, 2012, 04:35:41 AM »
Added a (hopefully) completed documentation of createList.
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #2 on: August 14, 2012, 09:06:58 AM »
This is a great start, emanuele.
Of course, it is very esoteric stuff -- completely incomprehensible to the uninitiated. And rightly so.  You learned it by immersing yourself in the code and trying things out to see what works (and does not work).
What pages do you think should like to these lists?
What warnings should be added -- some of this stuff is 2.1-only? Some of this stuff is the same in 2.0 and 2.1?
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #3 on: August 14, 2012, 03:24:26 PM »
Quote from: AngelinaBelle on August 14, 2012, 09:06:58 AM
This is a great start, emanuele.
Yes, exactly, it's just a start... there are many other things that would need documentation! :D

Quote from: AngelinaBelle on August 14, 2012, 09:06:58 AM
Of course, it is very esoteric stuff -- completely incomprehensible to the uninitiated. And rightly so.  You learned it by immersing yourself in the code and trying things out to see what works (and does not work).
lol
No, not really, it's just stuff not frequently used (I feel mostly because people doesn't know either how to use it or it exists at all).
What is now missing are examples...later.

Quote from: AngelinaBelle on August 14, 2012, 09:06:58 AM
What pages do you think should like to these lists?
No idea, there should be something related to development somewhere on the wiki, but I feel it is still a bit...not properly organised. :P

Quote from: AngelinaBelle on August 14, 2012, 09:06:58 AM
What warnings should be added -- some of this stuff is 2.1-only? Some of this stuff is the same in 2.0 and 2.1?
AFAIK there are just two things in creteList that are not in 2.0 and I already marked them with "(2.1 only)" (that probably should be changed to "(starting from 2.1)", but that's not so urgent at the moment :P).
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #4 on: August 16, 2012, 02:43:13 PM »
Quote from: emanuele on August 14, 2012, 03:24:26 PM
Quote from: AngelinaBelle on August 14, 2012, 09:06:58 AM
What pages do you think should like to these lists?
No idea, there should be something related to development somewhere on the wiki, but I feel it is still a bit...not properly organised. :P
I agree -- not properly organized. And it sounds like you cannot even find a page that is a logical "starting point" to jump to all of this new material.  That is a bad situation! It sounds like something doc team should be helping with -- organizing.
I'll see if I can figure it out a little bit.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #5 on: August 21, 2012, 12:38:40 PM »
Emanuele -- this documentation seems to be about two different things.  Is this correct?
Can you add a LITTLE bit more information about where such things are used?

If so, I can try to help organize.

I think it is a VERY good idea for everyone working in the code to share their understanding and wisdom on how it works.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #6 on: August 22, 2012, 06:29:17 AM »
It's in my to-do list along with adding some example. :)
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #7 on: August 23, 2012, 10:12:24 AM »
Every small hint you can add is something I could use to help organize the information you are producing.
Examples, of course, can always come later....

* The "home" of these things so described --- where they are initialized, etc.
This sort of thing.  As if they are properties of objects or some such thing.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #8 on: August 23, 2012, 12:53:22 PM »
Well, mod_cache just belongs here: http://wiki.simplemachines.org/smf/$user_info#mod_cache
I'll move there.

createList belongs to the function database here: http://support.simplemachines.org/function_db/index.php?action=view_function;id=748
but of course it wouldn't fit in there... :P
I think it could stay in several places:
http://wiki.simplemachines.org/smf/Category:Understanding_SMF's_source
http://wiki.simplemachines.org/smf/Category:Developing_SMF
http://wiki.simplemachines.org/smf/Category:Developing_Mods_and_Themes
http://wiki.simplemachines.org/smf/Category:Developing_Mods
http://wiki.simplemachines.org/smf/Category:Customizing_SMF

...too many...aren't two (developing SMF, customizing SMF...or developing SMF and theming SMF with customizing as redirect to developing) more than enough?
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #9 on: August 23, 2012, 01:43:32 PM »
These categories have grown up gradually.  It may be that we could do with fewer.
Developing and customizing SMF are clearly related.  Theming is, arguably, a sub-category, because, of course, it does involve SMF code.

As doc lead, of course, I am willing to take a lot of guidance from dev team, customization team, and some knowledgeable non-team members on how to categorize this information. My aim has to be to make it easier to use the info, and also to figure out where/how to add additional info.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #10 on: August 23, 2012, 04:20:59 PM »
I've always been unsure since the beginning on how "I" would like to see it...that's the biggest problem (on my side). lol

I'm not even sure of what kind of documents are already there...I should give a look, right?
* emanuele writes a note on his to-do list. O:)
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #11 on: August 23, 2012, 04:32:05 PM »
Quote from: emanuele on August 23, 2012, 04:20:59 PM
I've always been unsure since the beginning on how "I" would like to see it...that's the biggest problem (on my side). lol
Mine, too.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #12 on: August 24, 2012, 07:45:17 AM »
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #13 on: August 24, 2012, 07:53:04 AM »
Do you have a strong opinion about which categories would be useful, or do you think we should run a poll among devs and/or purple team and/or the mod-writing community?
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #14 on: August 24, 2012, 09:33:23 AM »
Death to polls. If someone is interested in contributing and has an opinion, he can speak here, no need for polls (you should know how I love this kind of things :P).

I think that at the moment the main goal is find all the pages. So less categories is good (IMHO), so we can have an overview.
Later if we come up with much more content then we can have more categories.
I'd say two:
1) one for dev in general (dev and mods) that can be Developing SMF
2) one for themes (that could be sub-cat of the first).
3) (optional but only because it already exists) http://wiki.simplemachines.org/smf/Category:SSI

Though, at the moment I remember three categories development-related that should not be touched:
http://wiki.simplemachines.org/smf/Category:Database_Package_Functions
http://wiki.simplemachines.org/smf/Category:Database_Functions
http://wiki.simplemachines.org/smf/Category:General_Utility_Functions
these are those that I'm using to categorise $smcFunc functions pages.
I think all of the pages in these categories are also in the SMF development category.
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #15 on: August 24, 2012, 02:05:45 PM »
For "poll", then substitute "conversation" Whatever.  Just to find out what works for various people at different levels of skill and familiarity with the code.

right now, you have the biggest voice. and you are also already very familiar with the code.
And the documentation.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins

Offline emanuele

  • Developer
  • SMF Super Hero
  • *
  • Posts: 11,891
  • Gender: Male
  • Because Orange is Orange
Re: Documenting what is in the code
« Reply #16 on: August 24, 2012, 03:27:58 PM »
lol

Not much with either of them! :P
* emanuele can break things pretty easily though.
Logged

Aiutateci ad aiutarvi: spiegate bene il vostro problema: no, "non funziona" non è una spiegazione!!
1) Cosa fai,
2) cosa ti aspetti,
3) cosa ottieni.

Offline AngelinaBelle

  • On Hiatus
  • SMF Hero
  • *
  • Posts: 6,673
Re: Documenting what is in the code
« Reply #17 on: August 27, 2012, 03:16:03 PM »
So, since nobody else is interested in this conversation, I will base my decisions on your statements.
Because I know far less about the intricacies of SMF coding and hence the suitability of the documentation.

My job here is simply to rearrange the information you have digested and then brought up.
Logged
If you do what you've always done, you'll get what you've always gotten. -- Anthony Robbins
Pages: [1]   Go Up
« previous next »