Fix forge docs

[grandizzy]

• update NATSpecs
• forge doc --serve --port 4000 and navigate to http://localhost:4000/

[ith-harvey]

As I was reviewing I found the function _encumberance to be confusing... If we only ever use this method to determine encumbered collateral I think the comment should indicate that is it's sole use case instead of what we have now ->

Calculates encumberance for a debt amount at a given price.

Names that lack descriptions in forge docs:

• ajnaPool_ in auctionStatus
• params in burn
• tokenId_ in claimRewards
• epochToClaim_ in claimRewards
• tokenId_ in stake
• tokenId_ in unstake
• pool_ and indexes_ in updateBucketExchangeRatesAndClaim
• tokenId_ and epochToCLaim_ in calculateRewards
• tokenId_ and bucketId_ in getBucketStateStakeInfo
• rewardsClaimedInEpoch_ in _calculateNewRewards

That is a start ^^ there are alot more. Worth manually reviewing versus me typing them all out : )

[grandizzy]

As I was reviewing I found the function _encumberance to be confusing... If we only ever use this method to determine encumbered collateral I think the comment should indicate that is it's sole use case instead of what we have now ->

Calculates encumberance for a debt amount at a given price.

Names that lack descriptions in forge docs:

• ajnaPool_ in auctionStatus
• params in burn
• tokenId_ in claimRewards
• epochToClaim_ in claimRewards
• tokenId_ in stake
• tokenId_ in unstake
• pool_ and indexes_ in updateBucketExchangeRatesAndClaim
• tokenId_ and epochToCLaim_ in calculateRewards
• tokenId_ and bucketId_ in getBucketStateStakeInfo
• rewardsClaimedInEpoch_ in _calculateNewRewards

That is a start ^^ there are alot more. Worth manually reviewing versus me typing them all out : )

Pls check with latest, they should be fixed. Takeaway is interface should have same params naming as impl in order to generate docs properly.

[ith-harvey]

LGTM

[EdNoepel]

Criticisms regarding scope and audit status:

• We had some inconsistency with some interfaces having trailing underscores in parameter and return type names, and other interfaces with no trailing underscores. If we had not completed any audits, I would favor no trailing underscores in interfaces. Just read comment interface should have same params naming as impl in order to generate docs properly; understood.
• Making LPs singular seems outside the purported scope of this change.

Other criticisms:

• I don't see why the term NFT should be backtick-quoted everywhere.

These concerns seem to be forge doc limitations:

• Not a fan of the === sprinkled everywhere, but we seemingly don't have much freedom to adjust formatting in forge doc output.
• Emitted events are not linked to the event definition; reader must hunt to determine arguments.
• Non-exposed methods should not be included in generated documentation.
• Free functions do not appear within the context of their containing library.

There are some valuable documentation improvements within, so in all it's a net positive. I don't think there is value adding a Makefile target. Happy to approve after a few minor inline concerns are addressed.

[grandizzy]

Other criticisms:

* I don't see why the term _NFT_ should be backtick-quoted everywhere.

Yeah, just wanted to make them inline with ERC20 and ERC721

These concerns seem to be forge doc limitations:

* Not a fan of the `===` sprinkled everywhere, but we seemingly don't have much freedom to adjust formatting in `forge doc` output.

was the best way I found to highlight different sections, can use different separator if there's a nicer one

[EdNoepel]

Looks good; thanks for this tedious work.

[MikeHathaway]

LGTM