What would people prefer?

- keep the Doxygen, but flesh it out properly, like I recently did for the
string_tokeniser (see
http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string__tokeniser.html),
or
- longer tutorial form written material, or
- short samples for individual components, or
- larger samples for each library, e.g. for WinSTL Registry library I'd show
a way to create/remove keys and values using reg_key and reg_value, and how
to enumerate keys and values using reg_key_sequence and reg_value_sequence,
or
- little discussions/tutorials here in the newsgroup, or
- all of the above, or
- something else entirely.

Cheers

Matthew

I would prefer a combination of 2 and 3.

For some cases just a small example of how to use something is sufficient, in other cases, a larger example shows users approriate situations to use your library. The large examples do not have to be all encompassing examples of how to use a particular library: for  the areas missed a small example would suffice.



One thing I really dislike about doxygen type documentation is that, yeah, you might have the complete class library and everything laid out, but it is not always straight forward as to how to use a particular item without actual examples.



> What would people prefer?
> 
> - keep the Doxygen, but flesh it out properly, like I recently did for
> the
> string_tokeniser (see
> http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string
> __tokeniser.html),
> or
> - longer tutorial form written material, or
> - short samples for individual components, or
> - larger samples for each library, e.g. for WinSTL Registry library
> I'd show
> a way to create/remove keys and values using reg_key and reg_value,
> and how
> to enumerate keys and values using reg_key_sequence and
> reg_value_sequence,
> or
> - little discussions/tutorials here in the newsgroup, or
> - all of the above, or
> - something else entirely.
> Cheers
> 
> Matthew
> 

I've finally looked at what you have for the string tokenizer function and that documentation looks really nice... that is what I think is best =)

Documentation such as:http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1basic__simple__string.html

leaves me wondering this question: Why should I choose it over std::string? Is it faster? Does it use a more highly optimized allocator? Is it geared towards multithreaded enviroments?

Those would be all questions I would be capable of answering by digging through the source code, but I don't currently have the ambition to do so =)

Please do not take me as too critical. I know it's a ton of work to keep good documentation.

"Josh Phillips" <raindog@macrohmasheen.com> wrote in message news:81fa68b115b5258c7fed4c42113de@news.digitalmars.com...
>I would prefer a combination of 2 and 3.
>
> For some cases just a small example of how to use something is sufficient, in other cases, a larger example shows users approriate situations to use your library. The large examples do not have to be all encompassing examples of how to use a particular library: for  the areas missed a small example would suffice.
>
>
>
> One thing I really dislike about doxygen type documentation is that, yeah, you might have the complete class library and everything laid out, but it is not always straight forward as to how to use a particular item without actual examples.
>
>
>
>> What would people prefer?
>>
>> - keep the Doxygen, but flesh it out properly, like I recently did for
>> the
>> string_tokeniser (see
>> http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string
>> __tokeniser.html),
>> or
>> - longer tutorial form written material, or
>> - short samples for individual components, or
>> - larger samples for each library, e.g. for WinSTL Registry library
>> I'd show
>> a way to create/remove keys and values using reg_key and reg_value,
>> and how
>> to enumerate keys and values using reg_key_sequence and
>> reg_value_sequence,
>> or
>> - little discussions/tutorials here in the newsgroup, or
>> - all of the above, or
>> - something else entirely.
>> Cheers
>>
>> Matthew
>>
>
> 

I think the best is actually all of 'em.

See... you have to have doxygen-ish docs for reference (only polished up to be easily browsable, I have a terrible time finding my way to what I want as they currently stand)

I liked the far more detailed explanation you wrote for tokenizer. The presentation's still bad, though. I know content is what matters most, but when looking at the reference, I often want to know a specific detail and presentation really helps at getting to it fast.

In this concrete case, for example, I've used tokenizer, I know what it does and why I'd want to use it, I'm just looking for a particular constructor's parameters, so... I don't want to have to scroll through all the explanation each time.

Note that I don't just mean "the long explanation should be at the bottom" (although I'm also saying that, maybe move it into a remarks section a la WinSDK Docs), but that what I'd like to get to quickly should be quickly accesible.

I still think adding "folding" is a good idea (yet I got stuck with doxygen's output and never did figure out how to do this). Something like:

<sample>
class string_tokenizer
{
- Typedefs
- Construction
- Methods
- Attributes
};
</sample>

Then each item inside can be expanded (unfolded?) and sought through faster.

I'll try and look into this ASAP.

***

Next, your item 2, short examples (I'm thinking things like "how to print the registry key tree", or "finding all files of a given extension"), would be helpful as a quick intro for a given component's new users.

Longer examples are useful IMO to "market" STLSoft. Showing how to make good use of the various components available (working on that CP article I promised, expect it in a couple of days)

And finally, discussions here are already available, so that doesn't need any work.


HTH,
Pablo

> What would people prefer?
> 
> - keep the Doxygen, but flesh it out properly, like I recently did for the string_tokeniser (see http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string__tokeniser.html), or
> - longer tutorial form written material, or
> - short samples for individual components, or
> - larger samples for each library, e.g. for WinSTL Registry library I'd show a way to create/remove keys and values using reg_key and reg_value, and how to enumerate keys and values using reg_key_sequence and reg_value_sequence, or
> - little discussions/tutorials here in the newsgroup, or
> - all of the above, or
> - something else entirely.
> 
> Cheers
> 
> Matthew

Hi,



Maybe because of constantly working with MSDN documentation I usually use it has a base comparison. But personally I find spewing out quality documentation really difficult. We must not forget that MSDN has people employed just to build that thing.



So having those two mindsets, in my opinion I would have to say the string_tokeniser type of documentation would suffice, since I believe that there are somewhat limited resources for building the documentation.



Although I like to suggest two improvements:

1) A Remarks section stating the authors "opinion" about the class (for example in cases you should use cases where another class is more adequate, tips, tricks, etc.)

2) A different organization for the information, trying something like MSDN I think would help since it's something familiar and people looking at the library for the first time would see something they already know.



Kind Regards

Cláudio Albuquerque



"Matthew" <nowhere@noaddress.co.us> wrote in message news:dsr8eu$a56$1@digitaldaemon.com...
> What would people prefer?
>
> - keep the Doxygen, but flesh it out properly, like I recently did for the
> string_tokeniser (see
> http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string__tokeniser.html),
> or
> - longer tutorial form written material, or
> - short samples for individual components, or
> - larger samples for each library, e.g. for WinSTL Registry library I'd
> show a way to create/remove keys and values using reg_key and reg_value,
> and how to enumerate keys and values using reg_key_sequence and
> reg_value_sequence, or
> - little discussions/tutorials here in the newsgroup, or
> - all of the above, or
> - something else entirely.
>
> Cheers
>
> Matthew
>
> 

Cláudio

Thanks for your input. Please check out the latest b64 release
(http://synesis.com.au/software/b64.html) and see if I've hit the nail (or
missed it by a mile).

Cheers

Matthew


"Cláudio Albuquerque" <0318222801@netcabo.pt> wrote in message news:e2q7du$13q9$1@digitaldaemon.com...
> Hi,
>
>
>
> Maybe because of constantly working with MSDN documentation I usually use
it
> has a base comparison. But personally I find spewing out quality documentation really difficult. We must not forget that MSDN has people employed just to build that thing.
>
>
>
> So having those two mindsets, in my opinion I would have to say the string_tokeniser type of documentation would suffice, since I believe that there are somewhat limited resources for building the documentation.
>
>
>
> Although I like to suggest two improvements:
>
> 1) A Remarks section stating the authors "opinion" about the class (for example in cases you should use cases where another class is more
adequate,
> tips, tricks, etc.)
>
> 2) A different organization for the information, trying something like
MSDN
> I think would help since it's something familiar and people looking at the library for the first time would see something they already know.
>
>
>
> Kind Regards
>
> Cláudio Albuquerque
>
>
>
> "Matthew" <nowhere@noaddress.co.us> wrote in message news:dsr8eu$a56$1@digitaldaemon.com...
> > What would people prefer?
> >
> > - keep the Doxygen, but flesh it out properly, like I recently did for
the
> > string_tokeniser (see
> >
http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string__tokeniser.html),
> > or
> > - longer tutorial form written material, or
> > - short samples for individual components, or
> > - larger samples for each library, e.g. for WinSTL Registry library I'd
> > show a way to create/remove keys and values using reg_key and reg_value,
> > and how to enumerate keys and values using reg_key_sequence and
> > reg_value_sequence, or
> > - little discussions/tutorials here in the newsgroup, or
> > - all of the above, or
> > - something else entirely.
> >
> > Cheers
> >
> > Matthew
> >
> >
>
>

short samples for individual components

Mathew,



Sorry for the delay, but finally I had the time to look at the B64 help.

I would like say congrats, the information contained in the help file in my opinion is very good, so you sure did hit this nail.

Though, again in my opinion, I think sometimes there is too much info in just one page.

Let me try to give you an example of what I mean. Regarding the help of the b64 lib, if I go to the "Namespace List"->"b64::cpp" I see a bunch of info Compounds, Typedefs, Functions, ....

For me I think it would be simpler if when I hit the "b64::cpp" branch it only displays the general information, by gerneral I refer to the following sections (Detailed Description,Compounds, Typedefs, Functions). Then I child branches I would have de detailed information, in this case regarding the typedef documentation and each function documentation.



Anyway I would like so say again congrats for the documentation, since I'm "silent" follower of the stlsoft lib for quite sometime and I've been seeing a great improvement in the quality of the documentation produced.


King Regards
Cláudio Albuquerque

"Matthew" <matthew@hat.stlsoft.dot.org> wrote in message news:e2sedk$1bk3$1@digitaldaemon.com...
> Cláudio
>
> Thanks for your input. Please check out the latest b64 release
> (http://synesis.com.au/software/b64.html) and see if I've hit the nail (or
> missed it by a mile).
>
> Cheers
>
> Matthew
>
>
> "Cláudio Albuquerque" <0318222801@netcabo.pt> wrote in message news:e2q7du$13q9$1@digitaldaemon.com...
>> Hi,
>>
>>
>>
>> Maybe because of constantly working with MSDN documentation I usually use
> it
>> has a base comparison. But personally I find spewing out quality documentation really difficult. We must not forget that MSDN has people employed just to build that thing.
>>
>>
>>
>> So having those two mindsets, in my opinion I would have to say the
>> string_tokeniser type of documentation would suffice, since I believe
>> that
>> there are somewhat limited resources for building the documentation.
>>
>>
>>
>> Although I like to suggest two improvements:
>>
>> 1) A Remarks section stating the authors "opinion" about the class (for example in cases you should use cases where another class is more
> adequate,
>> tips, tricks, etc.)
>>
>> 2) A different organization for the information, trying something like
> MSDN
>> I think would help since it's something familiar and people looking at
>> the
>> library for the first time would see something they already know.
>>
>>
>>
>> Kind Regards
>>
>> Cláudio Albuquerque
>>
>>
>>
>> "Matthew" <nowhere@noaddress.co.us> wrote in message news:dsr8eu$a56$1@digitaldaemon.com...
>> > What would people prefer?
>> >
>> > - keep the Doxygen, but flesh it out properly, like I recently did for
> the
>> > string_tokeniser (see
>> >
> http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string__tokeniser.html),
>> > or
>> > - longer tutorial form written material, or
>> > - short samples for individual components, or
>> > - larger samples for each library, e.g. for WinSTL Registry library I'd
>> > show a way to create/remove keys and values using reg_key and
>> > reg_value,
>> > and how to enumerate keys and values using reg_key_sequence and
>> > reg_value_sequence, or
>> > - little discussions/tutorials here in the newsgroup, or
>> > - all of the above, or
>> > - something else entirely.
>> >
>> > Cheers
>> >
>> > Matthew
>> >
>> >
>>
>>
>
> 

Cláudio

Thanks for the feedback. I'm glad that things have improved. To that end, please check out shwild (http://shwild.org/), as that's hopefully taking a next step in quality of docs. (Maybe ... <g>)

As for the Namespace busyness, I'm not sure there's much I can do about that without a *lot* of effort. I'm afraid at the moment I just don't have any spare bandwidth for it. But maybe in the future ...

Cheers

Matthew



"Cláudio Albuquerque" <0318222801@netcabo.pt> wrote in message news:e45tfh$2uv6$1@digitaldaemon.com...
>
> Mathew,
>
>
>
> Sorry for the delay, but finally I had the time to look at the B64 help.
>
> I would like say congrats, the information contained in the help file in my opinion is very good, so you sure did hit this nail.
>
> Though, again in my opinion, I think sometimes there is too much info in just one page.
>
> Let me try to give you an example of what I mean. Regarding the help of the b64 lib, if I go to the "Namespace List"->"b64::cpp" I see a bunch of info Compounds, Typedefs, Functions, ....
>
> For me I think it would be simpler if when I hit the "b64::cpp" branch it only displays the general information, by gerneral I refer to the following sections (Detailed Description,Compounds, Typedefs, Functions). Then I child branches I would have de detailed information, in this case regarding the typedef documentation and each function documentation.
>
>
>
> Anyway I would like so say again congrats for the documentation, since I'm "silent" follower of the stlsoft lib for quite sometime and I've been seeing a great improvement in the quality of the documentation produced.
>
>
> King Regards
> Cláudio Albuquerque
>
> "Matthew" <matthew@hat.stlsoft.dot.org> wrote in message news:e2sedk$1bk3$1@digitaldaemon.com...
>> Cláudio
>>
>> Thanks for your input. Please check out the latest b64 release
>> (http://synesis.com.au/software/b64.html) and see if I've hit the nail
>> (or
>> missed it by a mile).
>>
>> Cheers
>>
>> Matthew
>>
>>
>> "Cláudio Albuquerque" <0318222801@netcabo.pt> wrote in message news:e2q7du$13q9$1@digitaldaemon.com...
>>> Hi,
>>>
>>>
>>>
>>> Maybe because of constantly working with MSDN documentation I usually use
>> it
>>> has a base comparison. But personally I find spewing out quality documentation really difficult. We must not forget that MSDN has people employed just to build that thing.
>>>
>>>
>>>
>>> So having those two mindsets, in my opinion I would have to say the
>>> string_tokeniser type of documentation would suffice, since I believe
>>> that
>>> there are somewhat limited resources for building the documentation.
>>>
>>>
>>>
>>> Although I like to suggest two improvements:
>>>
>>> 1) A Remarks section stating the authors "opinion" about the class (for example in cases you should use cases where another class is more
>> adequate,
>>> tips, tricks, etc.)
>>>
>>> 2) A different organization for the information, trying something like
>> MSDN
>>> I think would help since it's something familiar and people looking at
>>> the
>>> library for the first time would see something they already know.
>>>
>>>
>>>
>>> Kind Regards
>>>
>>> Cláudio Albuquerque
>>>
>>>
>>>
>>> "Matthew" <nowhere@noaddress.co.us> wrote in message news:dsr8eu$a56$1@digitaldaemon.com...
>>> > What would people prefer?
>>> >
>>> > - keep the Doxygen, but flesh it out properly, like I recently did for
>> the
>>> > string_tokeniser (see
>>> >
>> http://www.synesis.com.au/software/stlsoft/help/classstlsoft_1_1string__tokeniser.html),
>>> > or
>>> > - longer tutorial form written material, or
>>> > - short samples for individual components, or
>>> > - larger samples for each library, e.g. for WinSTL Registry library
>>> > I'd
>>> > show a way to create/remove keys and values using reg_key and
>>> > reg_value,
>>> > and how to enumerate keys and values using reg_key_sequence and
>>> > reg_value_sequence, or
>>> > - little discussions/tutorials here in the newsgroup, or
>>> > - all of the above, or
>>> > - something else entirely.
>>> >
>>> > Cheers
>>> >
>>> > Matthew
>>> >
>>> >
>>>
>>>
>>
>>
>
> 

Please check out the latest recls distro to see if my tutorial stuff is improving.

There are 13 new examples: 8 recls core (C), 3 recls/C++, 2 recls/STL

I ran out of time to update the recls documentation or the sample/test programs, or example programs for the other mappings (D, .NET, Java, Python, Ruby), but those 13 are a serious attempt to writing simple and digestible tutorial-type programs, so I'm keen to hear opinions.

Cheers

Matthew