About the documentation format

jronald

jronald

FreeBSD API documents are like articles, and Microsoft's API document, i.e. MSDN, is more structural. I have used MSDN for a decade, among which used man pages as needed, my conclusion is that MSDN is more convenient than man pages absolutely. Why can not FreeBSD be better here?
 
Simple: you don't use MSDN documents on the console ("DOS prompt") which is actually common for manual pages. Different operating systems, different approaches.
 
ShelLuser said:
Simple: you don't use MSDN documents on the console ("DOS prompt") which is actually common for manual pages. Different operating systems, different approaches.
Click to expand...

I should say a structural form is better, and plain text is enough, because a good function should be self explained, and the user of the function should be more likely to check a part of the document of the function. Of course a whole one contains more information, information about every parameter, information about the relationship of the parameters, but when considering what the user demands, the extra information is irrelevant.

*nix style:
DESCRIPTION
The function fread reads nmemb elements of data, each size bytes long, from the stream pointed to by stream, storing them at the location given by ptr.
The function fwrite writes nmemb elements of data, each size bytes long, to the stream pointed to by stream, obtaining them from the location given by ptr.

For non-locking counterparts, see unlocked_stdio(3).

RETURN VALUE
fread and fwrite return the number of items successfully read or written (i.e., not the number of characters). If an error occurs, or the end-of-file is reached, the return value is a short item count (or zero).
fread does not distinguish between end-of-file and error, and callers must use feof(3) and ferror(3) to determine which occurred.
Click to expand...
MSDN style:
Parameters
--------------------------------------------------------------------------------
buffer
Storage location for data.

size
Item size in bytes.

count
Maximum number of items to be read.

stream
Pointer to FILE structure.

Return Value
--------------------------------------------------------------------------------
fread returns the number of full items actually read, which may be less than count if an error occurs or if the end of the file is encountered before reaching count . Use the feof or ferror function to distinguish a read error from an end-of-file condition. If size or count is 0, fread returns 0 and the buffer contents are unchanged. If stream or buffer is a null pointer, fread invokes the invalid parameter handler, as described in Parameter Validation. If execution is allowed to continue, this function sets errno to EINVAL and returns 0.

See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these, and other, error codes.
Click to expand...
 
MSDN is written for web pages. man pages are written for text. They need to fit on one machine installation and not take up a ton of space, which MSDN does. I don't understand why you didn't include the top half of the man page but the same synopsis of the parameters is included in the description. Plus, if you are just trying to look up the argument list, the man page has it at the top while the MSDN page doesn't show it at all in your example.

As a developer, I used to find MSDN quite verbose and frustrating to go through while the man pages are quick, well-written, and to the point.
 
drhowarddrfine said:
MSDN is written for web pages. man pages are written for text. They need to fit on one machine installation and not take up a ton of space, which MSDN does. I don't understand why you didn't include the top half of the man page but the same synopsis of the parameters is included in the description. Plus, if you are just trying to look up the argument list, the man page has it at the top while the MSDN page doesn't show it at all in your example.

As a developer, I used to find MSDN quite verbose and frustrating to go through while the man pages are quick, well-written, and to the point.
Click to expand...
Yes, MSDN is in HTML, it is a plus, only plain text will make differences when considering whether the format is structural or not.

I haven't included the top half, because I copied them from the http://www.linuxmanpages.com and MSDN, and they are in HTML, copying HTML as plain text may need some editing, and I think what omitted is only the function prototype, which is not important here.
 
It wont be long before Microsoft changes their MSDN again to make it more trendy. Manpages have remained the same throughout.

Who remembers this and this? I was actually looking for some VB6 stuff but that isn't even available anymore. Nice one Microsoft. Great docs!

Frankly I prefer consistency over simplicity.

I imagine MSDN also doesn't handle duplicate names very well. Whereas the traditional UNIX way of doing things splits things up into kernel, userland etc... (i.e fork(2), system(3)).
 
kpedersen said:
It wont be long before Microsoft changes their MSDN again to make it more trendy. Manpages have remained the same throughout.

Who remembers this and this? I was actually looking for some VB6 stuff but that isn't even available anymore. Nice one Microsoft. Great docs!

Frankly I prefer consistency over simplicity.

I imagine MSDN also doesn't handle duplicate names very well. Whereas the traditional UNIX way of doing things splits things up into kernel, userland etc... (i.e fork(2), system(3)).
Click to expand...

Now Microsoft almost monopolizes the desktop market, and is bureaucratic, not professional enough. But at the beginning, it was professional, for example, when deciding the format of the documents, etc.

Consistency is of course appreciated, but a chaos block of text is always consistent to another, because the condition of consistency is only that each is a block of text.
 
Oh, I agree with @kpedersen up there (you knew? What the heck gave that away? ;)).

I want to add insult to injury; even though I am actually a fan of Microsoft Windows 7, Microsoft Office 2010 and in a love/hate relationship with Visual Studio 2012. I'm not saying, there is enough in my post history.

The only motivation for this being my agitated state, me getting agitated again when being reminded that Microsoft is going to do away with TechNet and I guess I like the thread.

Before we go "Visual Basic 6 is ancient, no one uses that" a few questions come to mind. If Visual Basic 6 is so old that no one uses it any longer, then surely MS DOS is long gone by now? Errr.. Nope!.

Each to his own, but that strikes me as hypocrite. Strong words, easily said. Sure.

So how come that a MSDN blog is talking about Visual Basic 6 on Windows 8. Could it be people are more interested in MS DOS 6 than they are in Visual Basic 6?

I don't have facts to back this up, but for some reason I sincerely doubt this one.

My addition to the tread (apart from blowing off some steam): Before anyone goes "sure VB6 is old it had to go, that's the way thing go" reflect on this. There is nothing logical about their takes here and I'm under the impression I shared enough to back up that statement.

(Edit):

Rereading the whole thing, including my rant, we're slacking off (I'm just as much to blame, probably even more).

Documentation: HTML vs Text (correct me if I'm wrong, even then we'll get this back on track).

I don't agree. HTML, HyperText Markup Language. What is there to Mark Up on a text screen? Perhaps better put differently: what is there to mark up which common tools can't do?

Honestly; I don't care for processors which have to shift through all the HTML overhead merely to give me the look and feel I came to love and appreciate. Give me the speed of text and then I'll use that as I see fit.

Which isn't even touching subjects such as locate or apropos.

I don't think markup belongs here.
 
Last edited by a moderator:
jronald said:
Yes, MSDN is in HTML, it is a plus, only plain text will make differences when considering whether the format is structural or not.

...copying HTML as plain text may need some editing
Click to expand...
And now you spotted one of the first cracks. Remember, any HTML document is going to require a special viewer to read it and present it properly. It will also be a significantly larger file size. It also needs more time to be updated and made to work in all browsers and I'm sure someone will complain about accessibility. Now multiply that times several hundred files.
 
Not to mention HTML is all about presentation, not structure. There's not much you can do with an HTML document to convert it to another format if needed. A documentation format that enforces a structure is a much better choice if conversions to other formats are needed.
 
I mean even with only plain text, there is a difference: describe each parameter respectively or describe all the parameters in one block of text. And my opinion is that the former is better.
 
I see what you mean by separating it out into individual parameters rather than a paragraph containing them all. I can see some advantages to this.

Perhaps this stems from the fact that man pages are not generated from automatic documentation schemes such as Javadoc, Doxygen or Sandcastle / whatever MSDN uses.

Personally, in code I would much prefer a paragraph describing the function in general rather than some XML stuff duplicating the majority of the function signature. If this means that the generated documents cannot appear in the man pages, then I won't lose sleep over it.
 
kpedersen said:
I see what you mean by separating it out into individual parameters rather than a paragraph containing them all. I can see some advantages to this.

Perhaps this stems from the fact that man pages are not generated from automatic documentation schemes such as Javadoc, Doxygen or Sandcastle / whatever MSDN uses.

Personally, in code I would much prefer a paragraph describing the function in general rather than some XML stuff duplicating the majority of the function signature. If this means that the generated documents cannot appear in the man pages, then I won't lose sleep over it.
Click to expand...

Generating documents automatically brings something not intuitive in the code, but things can be easier, just add comments in the code, without tags for auto generating document, there are some advantages:

  • comment as little as possible, because it is better to let code be self-explanatory, essentially making a function be self-explanatory, BTW the ultimate function is main();
  • comment and code become more cohesive, practically they can be managed by a revision control system
  • when coding you can check the comment in the editor
  • you can comment the usage of a function in the head file, and the implementation detail in the implementation file
  • so the document or comments can evolve in an easier way, and so can the code, for example, if things become confusing (firstly the function is not self explained, secondly so does its comment), the code viewer will think, then he/she may understand something, if it is not his/her own problem, he/she is more likely to improve the document, even the code. A dilemma is that something is proved not good enough, and why is it allowed to be checked in?

So an open mind is important. Does FreeBSD get this?
 
@jronald, look at /usr/src/Makefile, you can run it with the doxygen parameter

Code: 
# doxygen             - Build API documentation of the kernel, needs doxygen.

It generates HTML FreeBSD kernel documentation.
 
Last edited by a moderator:
You must log in or register to reply here.
Back
Top