MSDN document is too simple -- sometimes

[Ryan Liu]

I agree best way to learn is to try out myself. But for simple things, I
hope document will be very clear and useful.

Sometime I feel the MSDN document is too simple, so simple just as repeating
name itself.

For instance, OpenFileDialog Class document:

"This class allows you to check whether a file exists and to open it. The
ShowReadOnly property determines whether a read-only check box appears in
the dialog box. The ReadOnlyChecked property indicates whether the read-only
check box is checked."

Bascially it explains "ReadOnlyChecked" means "Read Only Checked". But it
does not tell the core thing: what's this checkbox use for?

Is it used as a filter to only show read only files or it open files in read
only mode? (The doc also says its OpenFile method always open in readonly
mode).

Maybe this example is not very typical, but I often see similar things. Ocz,
this is same for JavaDoc, and comments in our own code. Boss says "must have
comment for all public methods", then sometime we do write useless things.

All the Best in 2008!

~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.

Ryan Liu
Shanghai Fengpu Software Co. Ltd
Shanghai , China

http://www.PowerCATI.com Powerful CATI!
http://www.fpsoft.net.cn
~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.~.

 

[Nicholas Paldino [.NET/C# MVP]]

Ryan,

Considering that the OpenFileDialog doesn't handle any of the file
operations, "Read Only" means it is used as a filter, not that it opens the
file in read only mode. The OpenFileDialog will return a path to you that
you can use, from there, you decide how to access the file.

 

[Ryan Liu]

Ryan,

Considering that the OpenFileDialog doesn't handle any of the file
operations, "Read Only" means it is used as a filter, not that it opens
the file in read only mode. The OpenFileDialog will return a path to you
that you can use, from there, you decide how to access the file.

Thanks, Nicholas.

I haven't try out, but when I read more doc, I think it is not used as a
filter, but a UI component to collect user's preference -- and the depends
on the honest programmer coding accordingly.

Regards,
Ryan

 

[Nicholas Paldino [.NET/C# MVP]]

Ryan,

Well, it is a filter. It's a filter on the UI element that the
OpenFileDialog exposes.

 

[Peter Duniho]

I agree best way to learn is to try out myself. But for simple things, I
hope document will be very clear and useful.

Sometime I feel the MSDN document is too simple, so simple just as
repeating name itself.

For instance, OpenFileDialog Class document:

"This class allows you to check whether a file exists and to open it.
The ShowReadOnly property determines whether a read-only check box
appears in the dialog box. The ReadOnlyChecked property indicates
whether the read-only check box is checked."

Bascially it explains "ReadOnlyChecked" means "Read Only Checked". But
it does not tell the core thing: what's this checkbox use for? [...]

You're right, the docs could elaborate better on _why_ you'd want to use
this. But as Nicholas says, the ShowReadOnly property is just a way of
"filtering" the behavior of the dialog box. That is, it controls an
optional UI element in the dialog box, allowing you to show it if you want.

If you have a need to allow users to tell you whether they want their
files opened in read-only mode or not, you can show this checkbox and then
use the value after the dialog is dismissed.

If you always open your files the same way, then you don't need this
option and can (and should) leave ShowReadOnly set to false.

Pete

 

[Ben Voigt [C++ MVP]]

I agree best way to learn is to try out myself. But for simple things, I
hope document will be very clear and useful.

Sometime I feel the MSDN document is too simple, so simple just as
repeating name itself.

For instance, OpenFileDialog Class document:

"This class allows you to check whether a file exists and to open it. The
ShowReadOnly property determines whether a read-only check box appears in
the dialog box. The ReadOnlyChecked property indicates whether the
read-only check box is checked."

Bascially it explains "ReadOnlyChecked" means "Read Only Checked". But it
does not tell the core thing: what's this checkbox use for?

It can't tell that, because you decide. All it does is provide a checkbox
to the user (if ShowReadOnly is set) and give you the result in
ReadOnlyChecked. How you handle that is up to you. Of course, it would be
a good idea to avoid writing to the file the user selected and specified
read-only, unless you want some very unhappy users, but you could decide
that the checkbox will trigger erasing the hard drive. Just be warned that
if you do, your users will be not only unhappy but probably homicidal.

The reason the OS doesn't just give you the file read-only, is because you
probably want to disable a bunch of menu options and so forth that would
change the file content. There's no one-size-fits-all answer.

 

[Peter Duniho]

[...]

Bascially it explains "ReadOnlyChecked" means "Read Only Checked". But
it
does not tell the core thing: what's this checkbox use for?

It can't tell that, because you decide.

I agree it can't tell you with certainty what the reader _will_ use the
checkbox for.

However, I think it's a failing of the documentation to not provide at
least one or two examples of why one _might_ use the checkbox. In that
respect, the docs definitely could tell you "what's this checkbox used
for?"

Pete

 

[Ben Voigt [C++ MVP]]

[...]

Bascially it explains "ReadOnlyChecked" means "Read Only Checked". But
it
does not tell the core thing: what's this checkbox use for?

It can't tell that, because you decide.

I agree it can't tell you with certainty what the reader _will_ use the
checkbox for.

However, I think it's a failing of the documentation to not provide at
least one or two examples of why one _might_ use the checkbox. In that
respect, the docs definitely could tell you "what's this checkbox used
for?"

More information, such as it is, here:
http://msdn2.microsoft.com/en-us/library/ms646839.aspx and here
http://msdn2.microsoft.com/en-us/library/ms646829(VS.85).aspx#open_file and
especially here
http://msdn2.microsoft.com/en-us/library/ms646960(VS.85).aspx

 

[Peter Duniho]

[...]
However, I think it's a failing of the documentation to not provide at
least one or two examples of why one _might_ use the checkbox. In that
respect, the docs definitely could tell you "what's this checkbox used
for?"

More information, such as it is, here:
http://msdn2.microsoft.com/en-us/library/ms646839.aspx and here
http://msdn2.microsoft.com/en-us/library/ms646829(VS.85).aspx#open_file
and especially here
http://msdn2.microsoft.com/en-us/library/ms646960(VS.85).aspx

But none of those links are part of the .NET documentation, nor is there
even a convenient way to get to them from the .NET documentation.

I have found that knowing the native Win32 API is very helpful in
understanding .NET, but it shouldn't be a prerequisite. The fact that
this information isn't in the .NET docs themselves is still a failing of
the documentation.

Pete

 

[Cor Ligthert[MVP]]

Pete,

I have found that knowing the native Win32 API is very helpful in
understanding .NET, but it shouldn't be a prerequisite. The fact that
this information isn't in the .NET docs themselves is still a failing of
the documentation.

I was thinking about almost the same reply as you.

However, I would not know what there can be added to these pages.

http://msdn2.microsoft.com/en-us/li...ms.openfiledialog.readonlychecked(VS.71).aspx

Cor

 

[Ignacio Machin \( .NET/ C# MVP \)]

Hi,

I think you selected a bad example

But in general you are right, sometimes the documentation is not the best or
most complete. But hey, it's really difficult (and time consuming) to
document all the framework.

A better example of it is in the thread "Testing a Comparer instance type'
there the documentation does not especify if a static property returns a new
instance each time that it's called or the same instance.

Of course, you can always contribute to the completeness of the docs by
using the "Community Content" section in MSDN