• Matthew (16/16) Feb 13 2006 What would people prefer?
• Josh Phillips (10/34) Feb 13 2006 I would prefer a combination of 2 and 3.
• Raindog (13/48) Feb 13 2006 I've finally looked at what you have for the string tokenizer function a...
• Pablo Aguilar (41/60) Feb 14 2006 I think the best is actually all of 'em.
• Cláudio Albuquerque (19/36) Apr 27 2006 Hi,
• Matthew (13/53) Apr 27 2006 Cláudio
• Cláudio Albuquerque (21/98) May 13 2006 Mathew,
• Matthew (11/119) May 13 2006 Cláudio
• Dejan Lekic (1/1) May 04 2006 short samples for individual components
• Matthew (9/9) Jun 18 2006 Please check out the latest recls distro to see if my tutorial stuff is

"Matthew" <nowhere noaddress.co.us> writes:

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_1stri
g__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

Josh Phillips <raindog macrohmasheen.com> writes:

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
 

"Raindog" <raindog macrohmasheen.com> writes:

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

 

Pablo Aguilar <pablo.aguilar gmail.com> writes:

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_1stri
g__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 Albuquerque" <0318222801 netcabo.pt> writes:

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_1stri
g__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

 

"Matthew" <matthew hat.stlsoft.dot.org> writes:

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 Albuquerque" <0318222801 netcabo.pt> writes:

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


 

"Matthew" <nowhere noaddress.co.us> writes:

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



 

Dejan Lekic <dejan nu6.org> writes:

short samples for individual components

"Matthew" <nowhere noaddress.co.us> writes:

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