Re: [Tcllib-devel] Graphops - Documentation

[Andreas K. <and...@ac...>]

Michal Antoniewski wrote:
> I reworked structuring like you said, please see if it now looks okay. 

Doing now ...

> In some places I left old style as I thought it looks better for those 
> cases (mainly case of not a lot of text and single arguments). If you 
> like I can change structure for them as well.

... Checking ... Greedy(Weighted)MaxIndependentSet, VerticesCover.

The shorter description does work for them. I would have preferred consistency. 
On the other hand I cannot complain too much here, given that I am often not 
fully consistent either in my work.

> For some procedures with e.g. single graph argument maybe it would look 
> better when it's written in a single line?

Actually for the non-structured description using 2 lines seems to be better 
than one.


> I've added some keywords and a graph theory section. Now, it has only 
> k-approximation algorithm definition but I will scan whole problem set, 
> so maybe some more interesting things could be added (also there is a 
> reference to wiki concerning approximation algorithms). Maybe each 
> problem could have it's definition in that section, but on the other 
> hand there are references which do the same.

I was thinking similarly when looking at the description, i.e. moving the 
definitions to the graph theory section. As for definitions which are the same, 
that would be no problem. You can have multiple references to the same thing.

Note here that we can not only have [section]s, but [subsection]s as well, 
which can be [sectref]'d. I.e. each specific definition could be put into a 
referencable sub-section, and then referenced directly.



>  
>  >>Any particular reason not modifying
>  >>       modules/struct/graphops.man
>  >>directly ?
>  
> Oh, I did so, but I created new documentation folder to separate 
> documentation work from the rest for better access (division) at SVN.

Hm. I am more comfortable with work within the existing structure. It also 
makes comparison easier, as I run a simple diff not only between last and 
current, but also the original baseline and current. The latter gives me a list 
of the files which have been added or changed within the tcllib structure. That 
tells us what we have to save from the project for integration. Well, assuming 
we wish to save only the changed parts. If we don't wish optimize (= save 
space) just saving the whole 'struct' directory would work as well. That also 
assumes that the work was done inside the existing directory and file structure.

> I was also doing some rechecking with test cases, so next upcoming 
> update will include tests.

Rev 44 ...


 >  419:	[emph Note:] Algorithm finds solutions dynamically. It compares all 
possible paths through the graph

When you say 'dynamically', do you mean 'Dynamic Programming' ?

 >  531:	[arg_def {Graph Object} G input]
 >  533:	Graph [arg G].

'The graph to cut.'

 >  535:	[arg_def {List} U input]
 >  536:	
 >  537:	Variable storing first set of nodes (cut) given by solution.
 >  538:	
 >  539:	[arg_def {List} V input]
 >  540:	
 >  541:	Variable storing second set of nodes (cut) given by solution.

U/V are also output, in a sense.


 >  704:	[arg_def {Integer} desiredGlow input]

Typo: Glow --> Flow

 >  727:	for sparse graphs, but also there exist some patological cases (those 
cases generally don't appear in practise) that

Typo: patological -> pathological


 >  728:	make time complexity increase exponentially with the growth of the 
number of nodes.
 >  729:	
 >  730:	[para]
 >  731:	[list_begin definitions]
 >  732:	
 >  733:	[def Arguments:]
 >  734:	[list_begin arguments]
 >  735:	[arg_def {Graph Object} G input]
 >  736:	Input graph.
 >  737:	[arg_def {Node} s input]
 >  738:	Source node for which all distances to each other node in graph [arg 
G] are computed.
 >  739:	[list_end][comment {-- arguments --}]
 >  740:	
 >  741:	[def "Options and result:"]
 >  742:	[list_begin options]
 >  743:	[opt_def -distances]

distances, not -distances, per the code (graphops.tcl, line 1706-1716).

Either fix documentation, or the code.

 >  744:	
 >  745:	When selected [arg outputFormat] is [const distances] - procedure 
returns dictionary containing
 >  746:	distances between source node [arg s] and each other node in graph 
[arg G].
 >  747:	
 >  748:	[opt_def -paths]

Ditto. paths, not -paths


 >  781:	[opt_def -graph]
 >  786:	[opt_def -tree]

Ditto. Compare graphops.tcl, lines 1811-1820.


 >  787:	
 >  788:	When selected [option outputFormar] is [option tree] - procedure 
returns a tree structure ([cmd struct::tree]),

outputFormat


 >  959:	[call [cmd struct::graph::op::createResidualGraph] [arg G] [arg f]]

 >  971:	[arg_def {Graph Object} G input]
 >  972:	Flow network (directed graph where each edge has set attribute: [term 
throughput] ).

Argument f is not documented.



 > 1010:	[call [cmd struct::graph::op::createLevelGraph] [arg Gf] [arg s]]
 > 1021:	[arg_def {Graph Object} G input]

G -> Gf




Andreas.