API Reference public review: Filesystem classes

Joomla! Documentation Workgroup

Moderator: Documentation

Locked
User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

API Reference public review: Filesystem classes

Post by Chris Davenport » Thu Apr 27, 2006 5:22 pm

The Developer Documentation Team has just completed its first batch of pages documenting the new Joomla! 1.5 API.  These pages are part of the developer documentation wiki and can be found here: http://dev.joomla.org/index.php?option= ... filesystem

The individual classes are as follows:
JArchive: http://dev.joomla.org/index.php?option= ... m:jarchive
JFile: http://dev.joomla.org/index.php?option= ... stem:jfile
JFolder: http://dev.joomla.org/index.php?option= ... em:jfolder
JPath: http://dev.joomla.org/index.php?option= ... stem:jpath

The Developer Documentation Team produces the API Reference pages by following a workflow procedure designed to ensure the quality of the documentation we produce.  Each page is subjected to an internal review process before being announced in this forum.  These pages are now considered to be under "public review" for a period of one month after which they are considered to be of high enough quality for general use.  To help readers to guage the likely quality of a particular page, every page includes a standard header block which includes a "Doc status" field which can be one of the following:

Work in progress indicates that the page is currently being compiled and its content should not be trusted.
Internal review indicates that the page is currently subject to an internal review by the Developer Documentation Team.
Public review indicates that review and feedback from members of the Joomla! community is encouraged.
Published indicates that the page has passed both internal and public review stages and its content can most probably be relied upon.
Periodic review indicates that the page, which would normally be in the "published" state, is currently undergoing a routine internal review to check its accuracy and quality.

Errors in any of these pages should, ideally, be reported in the Joomla! Official Documentation Project tracker here: http://forge.joomla.org/sf/tracker/do/l ... per_manual  Please include a link to the problem page.  If this is inconvenient then please report the problem in this thread.

We also welcome general feedback concerning these pages in this thread.  For errors/feedback about other pages please start another topic.

Thanks go to Ian MacLennon for this hard work in preparing these pages.

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
DanielMD
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 203
Joined: Thu Apr 13, 2006 9:46 pm
Location: Lisbon
Contact:

Re: API Reference public review: Filesystem classes

Post by DanielMD » Fri Apr 28, 2006 11:09 am

I do appreciate that this is getting documented, but i find hard to understand certain design decisions, i would like an introduction to the design goals of the class... something along the lines:

The primary pourpose of the class is to serve as a interface to create an ftp abstraction layer...
Or the design goals is to create a compressed file handler to replace this and that...

If people don't really understand what the pourpose of certain APIs is they will find it hard to understand what it does or why they should use this function instead of rolling their own.

Further than the explanation it would also be good to have example code.

P.S.: This was posted before i joined the documentation team and understood that the strong documentation phase is the beta phase, i hope anyone that reads this does not get confused with some of my statements, I hope this post script helps to clarify things.
Last edited by DanielMD on Fri May 19, 2006 5:16 pm, edited 1 time in total.
-> Documentation is the key to Joomla sucess if you have the time contribute to the Documentation Team
Check out: Joomla Video Tutorials @ http://joejoomla.com/index.php?option=c ... &Itemid=87

AmyStephen

Re: API Reference public review: Filesystem classes

Post by AmyStephen » Fri Apr 28, 2006 1:02 pm

Chris -

I have been watching Dan and you would be amazed at how smart he is in the technical arena. I believe he is willing to serve if you have use of him - he has lots of energy and passion and I think would produce good work for you.

Amy

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: API Reference public review: Filesystem classes

Post by Chris Davenport » Fri Apr 28, 2006 2:05 pm

Hi DanielMD,
DanielMD wrote: I do appreciate that this is getting documented, but i find hard to understand certain design decisions, i would like an introduction to the design goals of the class... something along the lines:
Yes, I agree.  But given the resources we have available we felt that it was better to get reasonable coverage of the new API as soon as possible so that we would then have a basis to add more detail later.  What we've come up with is a balance between breadth-first and depth-first.  The core devs have been producing some tutorial-style material, also on the wiki and at some point we will add links from these tutorials (and other material) into the API Reference, and vice versa, where appropriate.
DanielMD wrote: Further than the explanation it would also be good to have example code.

EDIT: Reading those pages in the wiki does not provide any more information than reading the API directly, so that is not of great use.
Each of the method/function pages contains at least one example of use (that was one of our most cherished design goals) although the class pages don't.  Again, this is a compromise that we have made given the resources at our disposal.  I believe that the code samples will prove to be the most useful part of the API Reference and I hope that we can expand the bank of such examples over time.  Writing and testing them has been the most time-consuming part of this exercise and this is where we can definitely "add value" over just reading the source code itself.  The code samples have also proven to be of use in testing the new API and in the process of documenting each function in detail we have been able to spot errors in the code and feed that back to the core devs.

We have a long way to go.  This is just 4 classes out of the 109 that are currently slated for documentation.  Since you are clearly keen and value good documentation I was going to suggest that you read and consider replying to this thread: http://forum.joomla.org/index.php/topic,53445.0.html about volunteering for the Dev Doc Team.  But I notice you've already done so!  manuman should be in touch with you soon and I look forward to being able to welcome you to the Team.

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

AmyStephen

Re: API Reference public review: Filesystem classes

Post by AmyStephen » Fri Apr 28, 2006 2:17 pm

Chris Davenport wrote: Since you are clearly keen and value good documentation I was going to suggest that you read and consider replying to this thread: http://forum.joomla.org/index.php/topic,53445.0.html about volunteering for the Dev Doc Team.  But I notice you've already done so!  manuman should be in touch with you soon and I look forward to being able to welcome you to the Team.
Chris - I think you will be very pleased with his help! And, it's going to be very good for the lad, as well! Amy

User avatar
DanielMD
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 203
Joined: Thu Apr 13, 2006 9:46 pm
Location: Lisbon
Contact:

Re: API Reference public review: Filesystem classes

Post by DanielMD » Fri Apr 28, 2006 2:34 pm

Chris Davenport wrote: Hi DanielMD,
Hi Chris, please call me Dan  :laugh:
Chris Davenport wrote: Yes, I agree.  But given the resources we have available we felt that it was better to get reasonable coverage of the new API as soon as possible so that we would then have a basis to add more detail later.  What we've come up with is a balance between breadth-first and depth-first.  The core devs have been producing some tutorial-style material, also on the wiki and at some point we will add links from these tutorials (and other material) into the API Reference, and vice versa, where appropriate.
I understand resources are few, ppl don't like to document, i find that i learn more wend i write and try to explain to other with tutorials or documentation it is a great way to learn new tricks or that something "does not work that way", so i would love to help creating some documentation so i can better understand the joomla design, and help improve it (but I will need some contact with core team members that introduced the code into the API to know what their goals are and give an overview of the design goals, and intended audience of the libraries).
Chris Davenport wrote: Each of the method/function pages contains at least one example of use (that was one of our most cherished design goals) although the class pages don't.
OOPS....  :-[ wend i first saw the pages i did not click the methods so i did not see the examples, sorry about that, but i think it should be made clear that their is example inside of every method. Add a new table column with  Method, Description, Example would make it very clear  :laugh:
Chris Davenport wrote: We have a long way to go.  This is just 4 classes out of the 109 that are currently slated for documentation.  Since you are clearly keen and value good documentation I was going to suggest that you read and consider replying to this thread: http://forum.joomla.org/index.php/topic,53445.0.html about volunteering for the Dev Doc Team.  But I notice you've already done so!  manuman should be in touch with you soon and I look forward to being able to welcome you to the Team.
I did try to get in touch with several ppl, that manage the documentation team, but got no reply, but i have been told by Amy (Hi Amy ;D) that things tend to move slow around here... and i am a fast paced guy, still i look forward to being part of the team, and do some documentation and really master the joomla CMS.

P.S.: This was posted before i joined the documentation team and understood that the strong documentation phase is the beta phase, i hope anyone that reads this does not get confused with some of my statements, I hope this post script helps to clarify things.
Last edited by DanielMD on Fri May 19, 2006 5:13 pm, edited 1 time in total.
-> Documentation is the key to Joomla sucess if you have the time contribute to the Documentation Team
Check out: Joomla Video Tutorials @ http://joejoomla.com/index.php?option=c ... &Itemid=87

User avatar
DanielMD
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 203
Joined: Thu Apr 13, 2006 9:46 pm
Location: Lisbon
Contact:

Re: API Reference public review: Filesystem classes

Post by DanielMD » Fri Apr 28, 2006 2:40 pm

AmyStephen wrote: Chris - I think you will be very pleased with his help! And, it's going to be very good for the lad, as well! Amy
Hehehe... hi Amy  :laugh:

Edit: this was posted before i joined the documentation team
Last edited by DanielMD on Fri May 19, 2006 5:06 pm, edited 1 time in total.
-> Documentation is the key to Joomla sucess if you have the time contribute to the Documentation Team
Check out: Joomla Video Tutorials @ http://joejoomla.com/index.php?option=c ... &Itemid=87

AmyStephen

Re: API Reference public review: Filesystem classes

Post by AmyStephen » Fri Apr 28, 2006 3:06 pm

DanielMD wrote:
AmyStephen wrote: Chris - I think you will be very pleased with his help! And, it's going to be very good for the lad, as well! Amy
Hehehe... hi Amy  :laugh:

I think you were right to warn me that stuff does move slow around here, but i think that is the way with most OS projects...

Mylady i sworn to defend thy honor....  ;D
Whoa! That is not quite what I meant!!! lol ... I am trying to give you advice to keep you out of trouble.  :-\ Be careful my young friend! For what you post seems slightly accusatory! We must support and help (which you will!) and not point out all weaknesses!  :P So, step lightly, otherwise, they shall burden you properly on the documentation team with much load!!!  8)

Your lady! Amy

User avatar
DanielMD
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 203
Joined: Thu Apr 13, 2006 9:46 pm
Location: Lisbon
Contact:

Re: API Reference public review: Filesystem classes

Post by DanielMD » Fri Apr 28, 2006 4:00 pm

And I will be happy to help :)

I understand that there is allot of changes hapenning at the same time, mambojoomla transition, the 1.5 redesign allot of stuff, and most people do this in part time... I do not mean any disrespect, I just wish things moved faster... i am of the impacient type (not a quality), documenting 109 (4 down 105 to go) classes is allot of ground to cover (let say 6 months?)... more?

Is there a release scheduele about this... I am afriad i am not on the loop about the inner working of the joomla teams.

Edit: This was posted before i joined the documentation team
Last edited by DanielMD on Fri May 19, 2006 5:06 pm, edited 1 time in total.
-> Documentation is the key to Joomla sucess if you have the time contribute to the Documentation Team
Check out: Joomla Video Tutorials @ http://joejoomla.com/index.php?option=c ... &Itemid=87

AmyStephen

Re: API Reference public review: Filesystem classes

Post by AmyStephen » Fri Apr 28, 2006 4:03 pm

I know, Dan! You are going to be a great member of the Joomla! community! You know that I am sold on you! I think you rock! No doubt! Amy

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1370
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: API Reference public review: Filesystem classes

Post by Chris Davenport » Fri Apr 28, 2006 5:14 pm

Hi Dan,
DanielMD wrote: I understand that there is allot of changes hapenning at the same time, mambojoomla transition, the 1.5 redesign allot of stuff, and most people do this in part time... I do not mean any disrespect, I just wish things moved faster... i am of the impacient type (not a quality), documenting 109 (4 down 105 to go) classes is allot of ground to cover (let say 6 months?)... more?

Is there a release scheduele about this... I am afriad i am not on the loop about the inner working of the joomla teams.
Things tend to move slowly because we are all volunteers with limited time available.  Who among us has not dreamt of getting paid to do this stuff so we could give up our day jobs?  :D  The other factor (and I'm sure you're already aware of this) is that we are all working in different time zones.  After a while you get used to when certain people are most likely to respond and the timing tends to follow the earth's rotation!  Sending messages west to east tends to be slower that east to west, if you see what I mean. ;)

I'm sure Shayne (manuman), who is in charge of the Dev Doc Team, will respond as soon as he is able.  It's probably the middle of the night where he is at the moment though!  Anyway, in the meantime you might like to look at some of our organisational documents here: http://help.joomla.org/content/category/37/150/106/.  We coordinate the API Reference using the Forge task manager here: http://forge.joomla.org/sf/projects/joo ... ntation_pr.

I'm afraid I'm going to be out of the loop for the next three days as it is May Day Bank Holiday here in the UK and I need to spend some time with the wife and kids as well as catch up on some sleep!  I'll talk to you again when I get back.

Regards,
Chris.
Chris Davenport

Davenport Technology Services http://www.davenporttechnology.com/
Lion Coppice http://www.lioncoppice.org/

User avatar
DanielMD
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 203
Joined: Thu Apr 13, 2006 9:46 pm
Location: Lisbon
Contact:

Re: API Reference public review: Filesystem classes

Post by DanielMD » Fri Apr 28, 2006 5:20 pm

Thanks for taking the time to reply and send those links i will take a look at them.

I wish you have a nice long weekend with your family, looking forward to working with you in making joomla #1 in documentation.  :laugh:
Last edited by DanielMD on Fri May 19, 2006 5:01 pm, edited 1 time in total.
-> Documentation is the key to Joomla sucess if you have the time contribute to the Documentation Team
Check out: Joomla Video Tutorials @ http://joejoomla.com/index.php?option=c ... &Itemid=87

User avatar
manuman
Joomla! Guru
Joomla! Guru
Posts: 891
Joined: Fri Aug 12, 2005 1:58 am
Location: Perth - Western Australia
Contact:

Re: API Reference public review: Filesystem classes

Post by manuman » Sat Apr 29, 2006 12:44 pm

Hi there Dan,

I have sent you a PM about joining our merry band  :D

Cheers
Shayne
Shayne Bartlett - Joomla Co-Founder
CTO/Web Architect: Elastik Limited https://elastik.space

User avatar
bigapple
Joomla! Apprentice
Joomla! Apprentice
Posts: 17
Joined: Mon Oct 24, 2005 9:48 am

Re: API Reference public review: Filesystem classes

Post by bigapple » Fri May 05, 2006 3:04 pm

Had a good look at it and it seems to me that it's a really good start.  :) 

Still I think that we could use a number of examples or templates for developing components, modules and plugins. It's hard to find the any source using this new API, so I guess I'm stuck to the old style.  :o And I won't be the only one, I'm afraid.

I know that this is heavy work though :-[ : But also  a number of code snippets in the documentation would great. 
Je clique, donc je code

User avatar
DanielMD
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 203
Joined: Thu Apr 13, 2006 9:46 pm
Location: Lisbon
Contact:

Re: API Reference public review: Filesystem classes

Post by DanielMD » Fri May 05, 2006 3:10 pm

Hi bigapple,

You have to look inside the methods, some have good examples, but other are still marked as TODO, and also if you click on the links of phpdocumentor you will be taken to the source files... hope this helps, as you noted this is still under heavy development, and we hope to do example chapters/tutorials etc... after we get the API documented, there is allot of work to be done in the documentation, wanna help? :)
Last edited by DanielMD on Fri May 05, 2006 3:12 pm, edited 1 time in total.
-> Documentation is the key to Joomla sucess if you have the time contribute to the Documentation Team
Check out: Joomla Video Tutorials @ http://joejoomla.com/index.php?option=c ... &Itemid=87

User avatar
ianmac
Joomla! Virtuoso
Joomla! Virtuoso
Posts: 4784
Joined: Sat Sep 24, 2005 11:01 pm
Location: Toronto, Canada

Re: API Reference public review: Filesystem classes

Post by ianmac » Sat May 06, 2006 4:57 am

You can also take a look at the core components for examples on how to develop components.  That's how I got started - I took a core component and started changing it to my will...

Ian

User avatar
bigapple
Joomla! Apprentice
Joomla! Apprentice
Posts: 17
Joined: Mon Oct 24, 2005 9:48 am

Re: API Reference public review: Filesystem classes

Post by bigapple » Mon May 08, 2006 1:22 pm

Right Ian, that might be the way to get started.  :)  Anyhow, the new API seems really promising with almost everything covered so I don't want to create any home-made solutions.
Je clique, donc je code


Locked

Return to “docs.joomla.org - Feedback/Information”