στις 18/02/2010 17:27, O/H Viktor Szakáts έγραψε:
Hi All,
So, I'd like to ask prospective contributors to _ignore
these_ and concentrate on our path. It has been said
many times: There will only be a documentation (in any
format, or medium), if someone actually writes them.
There is no other way.
Ok, let's (try to) write some documentation.
But before we start we have to know, what format should adopt. I mean, is
Nanforum format mandatory or we could follow a more human form?
For example, I am going to start documenting the functions HB_DirExists(),
HB_FileExists(), HB_FNameExists() found into src\rtl\hbfile.c
I choose to reproduce the structure of, say, "doc\en-EN\dir.txt", hence
i have
to write something like:
--------------------------------------------------------------------------------
/*
* The following parts are Copyright of the individual authors.
* www - http://www.harbour-project.org
*
* Copyright 2010 documentor's_name <[email protected]>
* Documentation for: HB_DirExists(), HB_FileExists(), HB_FNameExists()
*
* See COPYING for licensing terms.
*
*/
/* $DOC$
* $TEMPLATE$
* Function
* $NAME$
* HB_DirExists()
* $CATEGORY$
* API
* $SUBCATEGORY$
* FileSys
* $ONELINER$
* Determine if a directory exists
* $SYNTAX$
* HB_DirExists( [<cDirName>] ) --> lExists
* $ARGUMENTS$
* <cDirName> Directory name you want to check if exist.
* Can contain a path and Drive letter.
* Wildcards are NOT supported.
* If no path specified then the current path is used.
* SET DEFAULT are not evaluated.
* $RETURNS$
* HB_DirExists returns a logical TRUE if cDirName exists,
otherwise FALSE
* $DESCRIPTION$
* Here goes a detailed and very time consuming 'bla-bla' about the
function
* for which bla-bla is better to been left for the second
documantation wave
* and why not as an imagination exercise for the potential reader)
*
* $EXAMPLES$
* #include 'common.ch'
* Function Main( cDir )
* Default cDir to "lib"
* QOUT("Current directory: " CurDir() )
* QOUT("------------------------------------------------------")
* QOUT( "Directory: " cDir " does" IIF(
HB_DirExists(cDir), " ", "
NOT " ) "exist!" )
* cDir := "C:\"
* QOUT( "Directory: " cDir " does" IIF(
HB_DirExists(cDir), " ", "
NOT " ) "exist!" )
* QOUT()
* WAIT
* RETURN Nil
*
* $STATUS$
* R
* $COMPLIANCE$
* C
* $PLATFORMS$
* All(LFN)
* $FILES$
* Library is rtl
* $SEEALSO$
* HB_FileExists(), HB_FNameExists()
* $END$
*/
Now i have one/two more questions:
Are all those eye-bothering '$' & '*' necesary?
Also, are _all_ the above statements mandatory or we could leave out some
of them like $SUBCATEGORY$ $STATUS$ $COMPLIANCE$ etc. to make the txt
more
compact and 'quick-readable'
Supposing the answers are 'yes' let see how the above document
could be written:
------------------------------------------------------------------------------
/* $DOC$
FUNCNAME : HB_DirExists( <cDirName> ) --> lExists
SHORTDESC : Determine if a directory exists
ARGUMENTS : <cDirName> Directory name you want to check if exist.
Can contain a path and Drive letter.
Wildcards are NOT supported.
If no path specified then the current path is used.
SET DEFAULT are not evaluated.
RETURNS : HB_DirExists returns a logical TRUE if cDirName exists,
otherwise FALSE
DESCRIPTION:
[Here goes a detailed and very time consuming 'bla-bla' about the
function
for which bla-bla is better to left for the second documantation
wave
(and why not as an imagination exersize for the potential
reader) ...
...]
EXAMPLES:
#include 'common.ch'
Function Main( cDir )
Default cDir to "lib"
QOUT("Current directory: " CurDir() )
QOUT("------------------------------------------------------")
QOUT( "Directory: " cDir " does" IIF( HB_DirExists( cDir
), " ",
" NOT " ) "exist!" )
cDir := "C:\"
QOUT( "Directory: " cDir " does" IIF( HB_DirExists( cDir
), " ",
" NOT " ) "exist!" )
QOUT()
WAIT
RETURN Nil
PLATFORMS:
All(LFN)
FILES:
Library is rtl
SEE ALSO:
HB_FileExists(), HB_FNameExists()
$END$
*/
--------------------------------------------------------------------------------
An other critical question is how do i decide to document what?
That is, how do I know if the above documentation is not already written by
someone else? Obviously, somebody has to monitor the whole process,
keeping an
eye on 'who is documenting what' to avoid overlapping writing.
And of course, there are other things/questions that must be cleared up, but
can't been discussed all at once..
regards,
---
Pete
_______________________________________________
Harbour mailing list (attachment size limit: 40KB)
[email protected]
http://lists.harbour-project.org/mailman/listinfo/harbour
