COIN-OR::LEMON - Graph Library

Opened 11 years ago

Closed 11 years ago

#119 closed task (fixed)

Clean up the documentation

Reported by: Alpar Juttner Owned by: Peter Kovacs
Priority: blocker Milestone: LEMON 1.0 release
Component: documentation Version: release branch 1.0
Keywords: Cc:
Revision id:

Description

This task should be done after the 1.0 release branch will have been created.

Documentation contains references to tools that has not yet been ported from the svn. (For example there are empty modules is the doc.) These parts must be removed before the release.

Attachments (6)

9db8964f0cf6.patch (43.4 KB) - added by Peter Kovacs 11 years ago.
64f8f7cc6168.patch (15.2 KB) - added by Peter Kovacs 11 years ago.
2cc60866a0c9.patch (66.2 KB) - added by Peter Kovacs 11 years ago.
3a2e0692eaae.patch (10.9 KB) - added by Peter Kovacs 11 years ago.
merge-fix_2592532ee838.patch (852 bytes) - added by Peter Kovacs 11 years ago.
doc-impr_1e2d6ca80793.patch (5.2 KB) - added by Peter Kovacs 11 years ago.

Download all attachments as: .zip

Change History (21)

comment:1 Changed 11 years ago by Alpar Juttner

Component: coredocumentation

comment:2 Changed 11 years ago by Peter Kovacs

There are some tasks that should be done before creating the branch for 1.0, too. I think the followings are important.

  1. Related pages, that would be nice to port:
    • Named Parameters (there are a lot of reference for that, e.g. in bfs.h, dfs.h, dijkstra.h)
    • How to start using LEMON, Getting Started (they should be revised and maybe merged)
    • Quick Tour to LEMON (it contains some features that won't be part of the 1.0 release, e.g. LP, so maybe it would be better to postpone the port of this page)
  1. The modules page should be revised.
    • The name of the groups are inconsistent (e.g. "Path structures", "Graph structures", but "Maps"; using capitals in titles is not consequent; etc.).
    • I would prefer a new arrangement in which a module contains either submodules or elements (i.e. classes, functions etc.), but not both. E.g. In Maps module there are two sections: "Graph Maps", "Map Adaptors", so reading the modules page a user may think that all of the maps are either graph map or map adaptor. I suggest an other section called "Other Maps" or something similar. It would cause a more logical and clear list of modules that can be used like a "table of contents" for LEMON.
    • In a separate branch the empty modules should be removed.
  1. Since we don't have tutorial yet, a few demo programs would be important in the 1.0 release. Now we have three demos, but I suggest to add hello_lemon.cc, dijkstra_demo.cc, and topological_ordering.cc. They are really basic, but useful examples, and they are ready to add to the branch (see #81).
  1. The references in the doc should be checked: there shouldn't be unresolved ones (or not to many).
  1. All of the \todo commands should be removed form the codes. The simplier ones should be done, the others should be noted in tickets.

comment:3 in reply to:  2 ; Changed 11 years ago by Alpar Juttner

Replying to kpeter:

  1. Related pages, that would be nice to port:
    • Named Parameters (there are a lot of reference for that, e.g. in bfs.h, dfs.h, dijkstra.h)
    • How to start using LEMON, Getting Started (they should be revised and maybe merged)
    • Quick Tour to LEMON (it contains some features that won't be part of the 1.0 release, e.g. LP, so maybe it would be better to postpone the port of this page)

We have a separate repository for the LEMON Tutorial. These should probably go there.

  1. The modules page should be revised.
    • The name of the groups are inconsistent (e.g. "Path structures", "Graph structures", but "Maps"; using capitals in titles is not consequent; etc.).

Let's fix it.

  • I would prefer a new arrangement in which a module contains either submodules or elements (i.e. classes, functions etc.), but not both. E.g. In Maps module there are two sections: "Graph Maps", "Map Adaptors", so reading the modules page a user may think that all of the maps are either graph map or map adaptor. I suggest an other section called "Other Maps" or something similar. It would cause a more logical and clear list of modules that can be used like a "table of contents" for LEMON.

I cannot see why it is better to have a lot submodules called "Other Xyz" instead of just putting their contents into the parent modul.

  • In a separate branch the empty modules should be removed.

In fact, this was the original subject of this ticket. We must do it immediately after the release branch has been created.

  1. Since we don't have tutorial yet, a few demo programs would be important in the 1.0 release.

In no way. Everybody is welcome to improve the tutorial (which is currently virtually empty), but at the current phase of lemon-1.0 I do not want to include any new code of unclear aims or potentially raising new open issues.

  1. The references in the doc should be checked: there shouldn't be unresolved ones (or not to many).

Another one of original subjects of this ticket. We must do it immediately after the release branch has been created.

  1. All of the \todo commands should be removed form the codes. The simplier ones should be done, the others should be noted in tickets.

Yes, a patch for this is very welcome.

comment:4 in reply to:  3 ; Changed 11 years ago by Alpar Juttner

Replying to alpar:

Replying to kpeter:

  1. Related pages, that would be nice to port:
    • Named Parameters (there are a lot of reference for that, e.g. in bfs.h, dfs.h, dijkstra.h)
    • How to start using LEMON, Getting Started (they should be revised and maybe merged)
    • Quick Tour to LEMON (it contains some features that won't be part of the 1.0 release, e.g. LP, so maybe it would be better to postpone the port of this page)

We have a separate repository for the LEMON Tutorial. These should probably go there.

I was wrong here, a revised and probably more technical version the "Named Parameters" page should be a part of the doc.

comment:5 in reply to:  4 Changed 11 years ago by Alpar Juttner

Replying to alpar:

I was wrong here, a revised and probably more technical version the "Named Parameters" page should be a part of the doc.

I created separate ticked for this, see #147.

comment:6 in reply to:  3 Changed 11 years ago by Peter Kovacs

Replying to alpar:

Yes, a patch for this is very welcome.

I created separate ticked for this, see #149.

Changed 11 years ago by Peter Kovacs

Attachment: 9db8964f0cf6.patch added

comment:7 Changed 11 years ago by Peter Kovacs

[9db8964f0cf6] removes several doxygen warnings. It should be applied into the main branch as well as the 1.0 brnach.

comment:8 Changed 11 years ago by Alpar Juttner

Version: hg mainRelease branch 1.0

Changed 11 years ago by Peter Kovacs

Attachment: 64f8f7cc6168.patch added

comment:9 Changed 11 years ago by Peter Kovacs

[64f8f7cc6168] fixes more warnings. It should be applied to the main branch.

Changed 11 years ago by Peter Kovacs

Attachment: 2cc60866a0c9.patch added

comment:10 Changed 11 years ago by Peter Kovacs

Owner: changed from Alpar Juttner to Peter Kovacs
Status: newassigned

[2cc60866a0c9] reorganizes the modules section and removes the doc of all tools in the lemon/bits directory. It depends on [64f8f7cc6168]. It should went to the main branch, too.

Changed 11 years ago by Peter Kovacs

Attachment: 3a2e0692eaae.patch added

comment:11 Changed 11 years ago by Peter Kovacs

[3a2e0692eaae] removes all references to tools that have not yet been ported.

comment:12 Changed 11 years ago by Peter Kovacs

After applying [2cc60866a0c9] (to both branches) and [3a2e0692eaae] (to the 1.0 branch) I think the doc is practically clarified.

However it seems to be stange now, that the first reference in the "How to read the documentation" section is for the demo programs, since we have only three of them, and they not really representative or typical. So maybe this line should also be removed.

comment:13 Changed 11 years ago by Peter Kovacs

[2cc60866a0c9] went to the main branch, [3a2e0692eaae] went to the branch 1.0, and the last several changesets of the main branch were merged into the branch 1.0.

However the merge [12626fc94ccf] in branch 1.0 seems to be faulty, at least in the file doc/groups.dox. The attached patch [2592532ee838] fixes this file, but it would be important to check whether other files are merged correctly or not.

The other patch [1e2d6ca80793] contains several doc improvements on the head of the main repository. It should be applied to both branches.

Changed 11 years ago by Peter Kovacs

Changed 11 years ago by Peter Kovacs

Attachment: doc-impr_1e2d6ca80793.patch added

comment:14 Changed 11 years ago by Peter Kovacs

I think we can close this ticket.

comment:15 Changed 11 years ago by Alpar Juttner

Resolution: fixed
Status: assignedclosed
Note: See TracTickets for help on using tickets.