Re: [Sprawler-devel] Documentation of Existing Sprawler Methods and Classes

[J. K. <ja...@ka...>]

Hello.


> I think it looks great, and is very well done.  I have only read through
>  the beginning in detail, and skimmed the rest, but it looks awesome!
> I'm  curious about what everyone thinks we should do - have a separate
> document like this for the documentation, or insert it inline with the
> code?  I like inline, but it can make it harder to skim through code
> without all the docs.

Well, it's good to hear that you (and Mojo) like what I've come up with.
Mojo said that this will facilitate changes and new additions and that's
just what I was hoping to do with this. And might be best to leave this as
it is in order to help us understand it, see the big picture, etc. And
having it inline would be good as well. You can just copy and paste it all
in, and whenever changes are made, if you'd like to have it externally,
all it'll take is a quick script to update the external file. I think if
we just have the commented data have extra sharp symbols as comments (also
can be done by a short script) then this other script for updating the
external documentation can be doen automatically. In fact, I'm attaching a
text file with two separate Perl scrip[ts for doing those two things.


>>Did I go into too much or too little detail? There are some
>>inconsistencies in the format, and what is in it, (ie. I didn' include
>> the who-calls-what, but that may be a little to detailed for internal
>> documentation, perhaps it's more appropriate for more external
>>doumentation, whcih I may come up with next.) Also, it might not be
>> that wasy to undersand, in particular, where there are optional
>> parameters.
>>
>>
>
> Perfect amount of detail I think.

Perhaps it is, although maybe I should include more of the who-calls-who
for each method wherever possible, in order to give a better idea of not
just what the methods do, but how they interact. Also, maybe there are
some ways I can change the format to make it look more readable. I'd like
to  hear any suggestions you may have.

>>You can tell me what it is that you'd like done here, as I do plan on
>> expanding on it, cleaning it up, etc. I say we should also keep the big
>> picture in mind, and while Eric's Sprawler map was highly informative,
>> we need to bridge the gap between that and the code. This to help with
>> that. You could think of it as "Sprawler Code for Dummies" or whichever
>> you prefer. Anyway, I think I'll go look through that TODO list for
>> another task to work on, even though I may work a little more on this.
>> You can do what you want with it, though. And maybe this is a file that
>> can be kept separate, for a lookup of all classes and the methods in
>> them.
>>
>>
>
> Maybe we should put all these notes/docs on the website?

The SF website? Hmm, I was actually thinking of having it in the
repository. It is something that's be updated quite often and since it
gives somewhat low level details on the code, maybe it should be there
with the code in the repository. I was thinking that it'll be easier to
just commit this rather than update any of our websites.

>>On a remotely-related note, here's something to take a look at:
>>http://sourceforge.net/projects/dotproject/
>>I've taken a look at it and am thinking that is something we could use.
>> And I must say I like their home page. It's just another reason we can
>> think of setting up our own blog. And with this project, we cna keep
>> our internal documentation there, rather than have to go theough
>> mailing list archives. Just a thought.
>>
>>
>
> I've looked at that before. Very interesting - we could use it, but we
> don't even use the sourceforge stuff that much as it is.  Make we should
>  start?  There are task managers, etc.
>
> In fact - what do you think about putting all this documentation,
> todo's, etc, in the task manager and documentation manager?  Would you
> like to maintain this?

Silly me, I hadn't thought very much about using what's there. We
definitely need to have the Task Manager that's currently there updated
(it hasn't been in months) and the whole project description perhaps, as I
don't think we're the first to have the open source search technology. We
could also use the Doc Manager, although that isn't something I've seen
used very often. Maybe I can look into that, and then I can tell you if
that's something I'd like to work on (or if we should use what's there at
all.) But those are some good ideas.

Thanks,

J.K.

> Eric
>
> --
> ------------------------------------------------------------------ Eric
> Anderson     Sr. Systems Administrator    Centaur Technology
> Today is the tomorrow you worried about yesterday.
> ------------------------------------------------------------------
>
>
>
> -------------------------------------------------------
> This SF.Net email is sponsored by: IBM Linux Tutorials
> Free Linux tutorial presented by Daniel Robbins, President and CEO of
> GenToo technologies. Learn everything from fundamentals to system
> administration.http://ads.osdn.com/?ad_id=1470&alloc_id=3638&op=click
> _______________________________________________
> Sprawler-devel mailing list
> Spr...@li...
> https://lists.sourceforge.net/lists/listinfo/sprawler-devel