Hi Pete. I am writing a tool that will hide all "eye-bothering features" you have mentioned at the edit time. It's an optional tool, but It will agregate access to all docs directory tree (as they are already specified in doc/dirstruc.txt) from a single interface, and provide separated fields for each entry. The /*, $DOC$ etc in the output file will be created by the tool when you include a new command. Also, by scanning all doc dirs, It will be able to list and do a quick search in all documented commands, without the need to loading one by one, so writers can start writing a missing command with a single click.
On Fri, Feb 19, 2010 at 19:15, pete_westg <pete_we...@yahoo.gr> wrote: > στις 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 <m...@myoffice.gr> > * 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) > Harbour@harbour-project.org > http://lists.harbour-project.org/mailman/listinfo/harbour > _______________________________________________ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
