Command documentation and arguments order

[titan73]

I noticed the -obstructions was described twice in define_pdn_grid at https://github.com/The-OpenROAD-Project/OpenROAD/blob/master/src/pdn/README.md.
I intended to send a fix and noticed that the order of arguments between usage and description does not match.
Is there a policy regarding the order or argument? Should at least usage and description orders match? Or more should we use an alphabetical order?

[maliberty]

There is no policy currently but matching the order sounds reasonable. Alphabetical is also reasonable but a fair amount of work to update everything.

@gadfort FYI on pdn

[titan73]

As a beginner, alphabetical order is much better as when I'm trying to do something, I search for an option with a name that reflect that and this is hard to parse a not sorted list.
I guess important and frequent options are likely to be mandatory and he less ones optional and thus could be sorted separately like:

command
    -axxxx
    -bxxxx
    [-axxxx]
    [-bxxxx]

For newcomers, the examples in the doc show the more important & frequent options and experienced users already know them.

[maliberty]

Some commands take positional arguments as well (eg read_def ). Such arguments are often mandatory. How would you incorporate them?

[titan73]

Ah I forgot them. Indeed, we can't sort them so they need to stay where they are but sorting the rest would help searching options and particularly when there are a lot of them.

[maliberty]

How about

1. Mandatory flags
2. Optional flags
3. Positional

Alphabetical within each category.

[titan73]

Looks good to me. If @gadfort is agree I'll send a PR for define_pdn_grid.
Is this only for pdn or whole OR? If whole OR, what about adding it to developers rules?

[maliberty]

I think it makes sense globally. You could make a PR for the dev docs as well.

@luarss is this something we could test for in doc generation?

[gadfort]

@titan73 if you want to update the PDN docs, I'd be supportive of that

[titan73]

@gadfort I've just sent a PR

[luarss]

@maliberty Yes, in our current framework we can track all flags/args as long as it is not disabled for test. It could be a good issue for first time contributors.

[titan73]

That would be nice if possible also to check discrepancies between usage and descriptions.